1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
|
.. toctree::
:maxdepth: 1
File handling
=============
The *File* entity encapsulates all information of a dataset. *File*
entities keep some general information such as creation time and date,
format version etc. It is the entry-point to a *NIX* file.
File modes
----------
A *NIX* file can be opened in one of three modes:
1. ``nixio.FileMode.Overwrite`` Used for creating a new file or overwriting any content
in an existing one!
2. ``nixio.FileMode.ReadWrite`` Opens a file if it exists or otherwise creates a new
one. Does **not** overwrite existing content.
3. ``nixio.FileMode.ReadOnly`` Opens an existing file. The content can not be changed.
Will raise an error when the provided path is invalid (e.g. the file
does not exist).
Creating a new file
--------------------
.. literalinclude:: examples/fileCreate.py
:language: python
:lines: 3-13
:emphasize-lines: 7
:caption: Creating a new nix file with ``nixio.FileMode.Overwite`` or ``nixio.FileMode.ReadWrite`` (:download:`example code <examples/fileCreate.py>`
As mentioned above, using ``nixio.FileMode.Overwrite`` will destroy any existing content of the file. **By default**, if the ``FileMode`` flag is not specified, a file is opened in the ``FileMode.ReadWrite`` mode.
In this tutorial files will always have the extension ``*.nix``. This is not specified in the library and you are free to use any file extension.
Opening existing files
-----------------------
Use ``nixio.FileMode.ReadWrite`` or ``nixio.FileMode.ReadOnly`` to open
an existing file to work with the data. If you want to overwrite *any*
existing content in order to replace the file use
``nixio.FileMode.Overwite``.
In ``ReadOnly`` mode, you cannot change the file content:
.. literalinclude:: examples/fileCreate.py
:language: python
:lines: 14-23
In order to change the file content the file needs to be opened in ``ReadWrite`` mode:
.. literalinclude:: examples/fileCreate.py
:language: python
:lines: 25-28
Trying to open an non-existing file in ``ReadOnly`` mode will lead to an
error!
.. literalinclude:: examples/fileCreate.py
:language: python
:lines: 31-38
Enabling compression
--------------------
By default, data stored inside a *NIX* file will not be compressed. You
can switch on compression during file opening.
.. literalinclude:: examples/fileCreate.py
:language: python
:lines: 39-40
Compression is handled transparently by the hdf5-library, no further
user interaction is required. Compression reduces reading and writing
performance. You can choose to switch off compression on individual
*DataArray*\ s by passing the ``nixio.Compression.No`` flag at
the time of creation.
|
