# uproot.WritableDirectory

Defined in [uproot.writing.writable](https://github.com/scikit-hep/uproot5/blob/db953cf9827349b3d24eb6742404158c1dfd5481/src/uproot/writing/writable.py) on [line 468](https://github.com/scikit-hep/uproot5/blob/db953cf9827349b3d24eb6742404158c1dfd5481/src/uproot/writing/writable.py#L468).

| **Inheritance order:**                                                                                                                                                                                       |
|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| 1. `collections.abc.MutableMapping`<br/>2. `collections.abc.Mapping`<br/>3. `collections.abc.Collection`<br/>4. `collections.abc.Sized`<br/>5. `collections.abc.Iterable`<br/>6. `collections.abc.Container` |

### *class* uproot.writing.writable.WritableDirectory(path, file, cascading)

* **Parameters:**
  * **path** (*tuple* *of* *str*) – Path of directory names to this subdirectory; `()` for
    the root (first) directory.
  * **file** ([uproot.WritableFile](uproot.writing.writable.WritableFile.html.md)) – Handle to the file in
    which this directory can be found.
  * **cascading** (uproot.writing._cascade.CascadingDirectory) – The low-level
    directory object.

Represents a writable `TDirectory` from a ROOT file.

Be careful not to confuse [uproot.WritableFile](uproot.writing.writable.WritableFile.html.md) and
[uproot.WritableDirectory](uproot.writing.writable.WritableDirectory.html.md): files are for modifying global
information such as the TStreamerInfo and FreeSegments, whereas directories
are for data in local hierarchies.

A [uproot.WritableDirectory](uproot.writing.writable.WritableDirectory.html.md) is a Python `MutableMapping`,
which uses square bracket syntax to read, write, and delete objects:

```python
my_directory["histogram"]
my_directory["histogram"] = np.histogram(...)
del my_directory["histogram"]
```

Objects in ROOT files also have “cycle numbers,” which allow multiple versions
of an object to exist with the same name. A cycle number may be specified after
a semicolon for *reading* and *deleting* only:

```python
my_directory["histogram;2"]
del my_directory["histogram;2"]
```

When *writing*, cycle numbers are generated to avoid overwriting previous objects:

```python
my_directory["histogram"] = np.histogram(...)   # creates a new histogram
my_directory["histogram"] = np.histogram(...)   # creates another histogram
```

Note that this is unlike a Python `MutableMapping`, which would overwrite the
object in the second assignment. However, it is the way ROOT I/O works; use `del`
to remove unwanted versions of objects.

Any types of objects that can be read from a [uproot.ReadOnlyDirectory](uproot.reading.ReadOnlyDirectory.html.md)
can be read from a [uproot.WritableDirectory](uproot.writing.writable.WritableDirectory.html.md) *except TTrees*. A
TTree can only be read from a [uproot.ReadOnlyDirectory](uproot.reading.ReadOnlyDirectory.html.md) if it was
created in this open file handle, and then it returns a [uproot.WritableTree](uproot.writing.writable.WritableTree.html.md)
instead of the [uproot.TTree](uproot.behaviors.TTree.TTree.html.md) that you would get from a
[uproot.ReadOnlyDirectory](uproot.reading.ReadOnlyDirectory.html.md). Readable TTrees and writable TTrees are
distinct, with separate sets of features.

Note that subdirectories can be created by assigning to path names that include
slashes:

```python
my_directory["subdir1/subdir2/new_object"] = new_object
```

Subdirectories created this way will never be empty; to make an empty directory,
use [mkdir](#uproot-writing-writable-writabledirectory-mkdir).

Similarly, non-empty RNTuples can be created by assignment starting in Uproot
v5.7.0 (see [uproot.writing.writable.WritableNTuple](uproot.writing.writable.WritableNTuple.html.md) for recognized
RNTuple-like data), but empty RNTuples require the
[mkrntuple](#uproot-writing-writable-writabledirectory-mkrntuple) method.
Writing a TTree requires the [mktree](#uproot-writing-writable-writabledirectory-mktree) method.

<a id="uproot-writing-writable-writabledirectory-path"></a>

## path

#### WritableDirectory.path

Path of directory names to this subdirectory as a tuple of strings; e.g. `()`
for the root (first) directory.

<a id="uproot-writing-writable-writabledirectory-object-path"></a>

## object_path

#### WritableDirectory.object_path

Path of directory names to this subdirectory as a single string, delimited
by slashes.

<a id="uproot-writing-writable-writabledirectory-file-path"></a>

## file_path

#### WritableDirectory.file_path

Filesystem path of the open file, or None if using a file-like object.

<a id="uproot-writing-writable-writabledirectory-file"></a>

## file

#### WritableDirectory.file

Handle to the [uproot.WritableDirectory](uproot.writing.writable.WritableDirectory.html.md) in which
this directory can be found.

<a id="uproot-writing-writable-writabledirectory-close"></a>

## close

#### WritableDirectory.close()

Explicitly close the file.

(Files can also be closed with the Python `with` statement, as context
managers.)

After closing, objects cannot be read from or written to the file.

<a id="uproot-writing-writable-writabledirectory-closed"></a>

## closed

#### WritableDirectory.closed

True if the file has been closed; False otherwise.

The file may have been closed explicitly with
[close](uproot.writing.writable.WritableFile.html.md#uproot-writing-writable-writablefile-close) or implicitly in the Python
`with` statement, as a context manager.

After closing, objects cannot be read from or written to the file.

<a id="uproot-writing-writable-writabledirectory-compression"></a>

## compression

#### WritableDirectory.compression

Compression algorithm and level ([uproot.compression.Compression](uproot.compression.Compression.html.md) or None)
for new objects added to the file.

This property can be changed, which allows you to write different objects
with different compression settings.

<a id="uproot-writing-writable-writabledirectory-keys"></a>

## keys

#### WritableDirectory.keys(\*, recursive=True, cycle=True, filter_name=<function no_filter>, filter_classname=<function no_filter>)

* **Parameters:**
  * **recursive** (*bool*) – If True, descend into any nested subdirectories.
    If False, only return the names of objects directly accessible
    in this `TDirectory`.
  * **cycle** (*bool*) – If True, include the cycle numbers in those names.
  * **filter_name** (None, glob string, regex string in `"/pattern/i"` syntax, function of str → bool, or iterable of the above) – A
    filter to select keys by name.
  * **filter_classname** (None, glob string, regex string in `"/pattern/i"` syntax, function of str → bool, or iterable of the above) – A
    filter to select keys by C++ (decoded) classname.

Returns the names of the objects in this `TDirectory` as a list of
strings.

Note that this does not read any data from the file.

<a id="uproot-writing-writable-writabledirectory-values"></a>

## values

#### WritableDirectory.values(\*, recursive=True, filter_name=<function no_filter>, filter_classname=<function no_filter>)

* **Parameters:**
  * **recursive** (*bool*) – If True, descend into any nested subdirectories.
    If False, only return objects directly accessible in this
    `TDirectory`.
  * **filter_name** (None, glob string, regex string in `"/pattern/i"` syntax, function of str → bool, or iterable of the above) – A
    filter to select keys by name.
  * **filter_classname** (None, glob string, regex string in `"/pattern/i"` syntax, function of str → bool, or iterable of the above) – A
    filter to select keys by C++ (decoded) classname.

Returns objects in this `TDirectory` as a list of
[uproot.Model](uproot.model.Model.html.md).

Note that this reads all objects that are selected by `filter_name`
and `filter_classname`.

<a id="uproot-writing-writable-writabledirectory-items"></a>

## items

#### WritableDirectory.items(\*, recursive=True, cycle=True, filter_name=<function no_filter>, filter_classname=<function no_filter>)

* **Parameters:**
  * **recursive** (*bool*) – If True, descend into any nested subdirectories.
    If False, only return (name, object) pairs directly accessible
    in this `TDirectory`.
  * **cycle** (*bool*) – If True, include the cycle numbers in the names.
  * **filter_name** (None, glob string, regex string in `"/pattern/i"` syntax, function of str → bool, or iterable of the above) – A
    filter to select keys by name.
  * **filter_classname** (None, glob string, regex string in `"/pattern/i"` syntax, function of str → bool, or iterable of the above) – A
    filter to select keys by C++ (decoded) classname.

Returns (name, object) pairs for objects in this `TDirectory` as a
list of 2-tuples of (str, [uproot.Model](uproot.model.Model.html.md)).

Note that this reads all objects that are selected by `filter_name`
and `filter_classname`.

<a id="uproot-writing-writable-writabledirectory-classnames"></a>

## classnames

#### WritableDirectory.classnames(\*, recursive=True, cycle=True, filter_name=<function no_filter>, filter_classname=<function no_filter>)

* **Parameters:**
  * **recursive** (*bool*) – If True, descend into any nested subdirectories.
    If False, only return the names and classnames of objects
    directly accessible in this `TDirectory`.
  * **cycle** (*bool*) – If True, include the cycle numbers in the names.
  * **filter_name** (None, glob string, regex string in `"/pattern/i"` syntax, function of str → bool, or iterable of the above) – A
    filter to select keys by name.
  * **filter_classname** (None, glob string, regex string in `"/pattern/i"` syntax, function of str → bool, or iterable of the above) – A
    filter to select keys by C++ (decoded) classname.

Returns the names and C++ (decoded) classnames of the objects in this
`TDirectory` as a dict of str → str.

Note that this does not read any data from the file.

<a id="uproot-writing-writable-writabledirectory-iterkeys"></a>

## iterkeys

#### WritableDirectory.iterkeys(\*, recursive=True, cycle=True, filter_name=<function no_filter>, filter_classname=<function no_filter>)

* **Parameters:**
  * **recursive** (*bool*) – If True, descend into any nested subdirectories.
    If False, only return the names of objects directly accessible
    in this `TDirectory`.
  * **cycle** (*bool*) – If True, include the cycle numbers in those names.
  * **filter_name** (None, glob string, regex string in `"/pattern/i"` syntax, function of str → bool, or iterable of the above) – A
    filter to select keys by name.
  * **filter_classname** (None, glob string, regex string in `"/pattern/i"` syntax, function of str → bool, or iterable of the above) – A
    filter to select keys by C++ (decoded) classname.

Returns the names of the objects in this `TDirectory` as an iterator
over strings.

Note that this does not read any data from the file.

<a id="uproot-writing-writable-writabledirectory-itervalues"></a>

## itervalues

#### WritableDirectory.itervalues(\*, recursive=True, filter_name=<function no_filter>, filter_classname=<function no_filter>)

* **Parameters:**
  * **recursive** (*bool*) – If True, descend into any nested subdirectories.
    If False, only return objects directly accessible in this
    `TDirectory`.
  * **filter_name** (None, glob string, regex string in `"/pattern/i"` syntax, function of str → bool, or iterable of the above) – A
    filter to select keys by name.
  * **filter_classname** (None, glob string, regex string in `"/pattern/i"` syntax, function of str → bool, or iterable of the above) – A
    filter to select keys by C++ (decoded) classname.

Returns objects in this `TDirectory` as an iterator over
[uproot.Model](uproot.model.Model.html.md).

Note that this reads all objects that are selected by `filter_name`
and `filter_classname`.

<a id="uproot-writing-writable-writabledirectory-iteritems"></a>

## iteritems

#### WritableDirectory.iteritems(\*, recursive=True, cycle=True, filter_name=<function no_filter>, filter_classname=<function no_filter>)

* **Parameters:**
  * **recursive** (*bool*) – If True, descend into any nested subdirectories.
    If False, only return (name, object) pairs directly accessible
    in this `TDirectory`.
  * **cycle** (*bool*) – If True, include the cycle numbers in the names.
  * **filter_name** (None, glob string, regex string in `"/pattern/i"` syntax, function of str → bool, or iterable of the above) – A
    filter to select keys by name.
  * **filter_classname** (None, glob string, regex string in `"/pattern/i"` syntax, function of str → bool, or iterable of the above) – A
    filter to select keys by C++ (decoded) classname.

Returns (name, object) pairs for objects in this `TDirectory` as an
iterator over 2-tuples of (str, [uproot.Model](uproot.model.Model.html.md)).

Note that this reads all objects that are selected by `filter_name`
and `filter_classname`.

<a id="uproot-writing-writable-writabledirectory-iterclassnames"></a>

## iterclassnames

#### WritableDirectory.iterclassnames(\*, recursive=True, cycle=True, filter_name=<function no_filter>, filter_classname=<function no_filter>)

* **Parameters:**
  * **recursive** (*bool*) – If True, descend into any nested subdirectories.
    If False, only return the names and classnames of objects
    directly accessible in this `TDirectory`.
  * **cycle** (*bool*) – If True, include the cycle numbers in the names.
  * **filter_name** (None, glob string, regex string in `"/pattern/i"` syntax, function of str → bool, or iterable of the above) – A
    filter to select keys by name.
  * **filter_classname** (None, glob string, regex string in `"/pattern/i"` syntax, function of str → bool, or iterable of the above) – A
    filter to select keys by C++ (decoded) classname.

Returns the names and C++ (decoded) classnames of the objects in this
`TDirectory` as an iterator of 2-tuples of (str, str).

Note that this does not read any data from the file.

<a id="uproot-writing-writable-writabledirectory-mkdir"></a>

## mkdir

#### WritableDirectory.mkdir(name, \*, initial_directory_bytes=None)

* **Parameters:**
  * **name** (*str*) – Name of the new subdirectory.
  * **initial_directory_bytes** (*None* *or* *int*) – Number of bytes to allocate
    for the new directory, so that TKeys can be added to it without
    immediately needing to rewrite the block. If None, the
    [uproot.WritableFile](uproot.writing.writable.WritableFile.html.md)’s value is used.

Creates an empty subdirectory in this directory.

Note that subdirectories can be created by assigning to path names that
include slashes:

```python
my_directory["subdir1/subdir2/new_object"] = new_object
```

but subdirectories created this way will never be empty. Use this method
to make an empty directory or to control directory parameters.

<a id="uproot-writing-writable-writabledirectory-mktree"></a>

## mktree

#### WritableDirectory.mktree(name, branch_types_or_data, title='', \*, counter_name=<function WritableDirectory.<lambda>>, field_name=<function WritableDirectory.<lambda>>, initial_basket_capacity=10, resize_factor=10.0)

* **Parameters:**
  * **name** (*str*) – Name of the new TTree.
  * **type** (*branch_types_or_data* *(**dict* *of* *str → NumPy dtype/Awkward*) – or dict of str → data to be written in the TBranch): Name
    and type specification for the TBranches. If the values are not valid
    type specifications, they are assumed to be the actual data to be written.

:param
: and type specification for the TBranches. If the values are not valid
  type specifications, they are assumed to be the actual data to be written.

* **Parameters:**
  * **title** (*str*) – Title for the new TTree.
  * **counter_name** (*callable* *of* *str → str*) – Function to generate counter-TBranch
    names for Awkward Arrays of variable-length lists. Arrays whose
    counters get the same name share one counter TBranch. A counter
    replaces a scalar integer TBranch of the same name with an
    `int32` one; a name collision with any other TBranch raises
    a ValueError.
  * **field_name** (*callable* *of* *str → str*) – Function to generate TBranch
    names for columns of an Awkward record array or a Pandas DataFrame.
  * **initial_basket_capacity** (*int*) – Number of TBaskets that can be written to the
    TTree without rewriting the TTree metadata to make room.
  * **resize_factor** (*float*) – When the TTree metadata needs to be rewritten,
    this specifies how many more TBasket slots to allocate as a multiplicative
    factor.

Creates an empty TTree in this directory.

Note that starting in v5.7.0, Uproot uses RNTuples as the default format for writing
data when using the dict-like assignment syntax. Writing a TTree requires using this
method.

<a id="uproot-writing-writable-writabledirectory-mkrntuple"></a>

## mkrntuple

#### WritableDirectory.mkrntuple(name, type_spec_or_data, description='')

* **Parameters:**
  * **name** (*str*) – Name of the new RNTuple.
  * **type** (*type_spec_or_data* *(**dict* *of* *str → NumPy dtype/Awkward*) – Awkward RecordForm, or data in the form of a RecordArray, Pandas dataframe, or dict): Name
    and type specification for the fields. If a RecordForm is provided,
    the RNTuple will be empty. If a RecordArray is provided, the RNTuple
    will be initialized with the input data.

:param
: and type specification for the fields. If a RecordForm is provided,
  the RNTuple will be empty. If a RecordArray is provided, the RNTuple
  will be initialized with the input data.

* **Parameters:**
  **description** (*str*) – Description for the new RNTuple.

Creates an empty RNTuple in this directory.

Note that starting in v5.7.0, non-empty RNTuples can be created by
assigning RNTuple-like data to a directory:

```python
my_directory["ntuple"] = {"field1": np.array(...), "field2": ak.Array(...)}
```

but RNTuples created this way will never be empty. Use this method
to make an empty RNTuple or to control its parameters.

<a id="uproot-writing-writable-writabledirectory-copy-from"></a>

## copy_from

#### WritableDirectory.copy_from(source, \*, filter_name=<function no_filter>, filter_classname=<function no_filter>, rename=<function no_rename>, require_matches=True)

* **Parameters:**
  * **source** ([uproot.WritableDirectory](uproot.writing.writable.WritableDirectory.html.md) or [uproot.ReadOnlyDirectory](uproot.reading.ReadOnlyDirectory.html.md)) – Directory from which to copy.
  * **filter_name** (None, glob string, regex string in `"/pattern/i"` syntax, function of str → bool, or iterable of the above) – A
    filter to select keys by name.
  * **filter_classname** (None, glob string, regex string in `"/pattern/i"` syntax, function of str → bool, or iterable of the above) – A
    filter to select keys by C++ (decoded) classname.
  * **rename** (None, regex string in `"/from/to/"` syntax, dict of str → str, function of str → str, or iterable of the above) – A
    function to convert old names into new names.
  * **require_matches** (*bool*) – If True and the filters do not match any data, raise
    a `ValueError`.

Bulk-copy method to copy data from one ROOT file to another without interpretation
or even decompression/recompression.

This method will likely have performance advantages over copying objects one
at a time, in part because it avoids interpretation and decompression/recompression,
and also because it collects TStreamerInfo from all of the data types and
rewrites the output file’s TStreamerInfo exactly once.

<a id="uproot-writing-writable-writabledirectory-update"></a>

## update

#### WritableDirectory.update(pairs=None, \*\*more_pairs)

* **Parameters:**
  * **pairs** (*dict* *or* *pairs* *of* *str → writable data*) – Names and data to write.
  * **more_pairs** (*dict* *or* *pairs* *of* *str → writable data*) – More names and data to write.

Bulk-update function, like assignment, but it collects TStreamerInfo for a single
update.