For a Python programmer this is most probably the most important part of this very short documentation. libpnicore provides a set of exception types which are used by itself and other libraries like libpniio. pni.core provides wrappers to some of these exceptions and include translator functions which ensure that the appropriate Python exception is raised for every C++ exception.
Some of the exceptions provided by libpnicore can be mapped directly on default exceptions already provided by Python. These are the following ones
| C++ exception | Python exception |
|---|---|
| pni::core::memory_allocation_error | MemoryError |
| pni::core::memory_not_allocated_error | MemoryError |
| pni::core::index_error | IndexError |
| pni::core::key_error | KeyError |
| pni::core::not_implemented_error | NotImplementedError |
| pni::core::value_error | ValueError |
| pni::core::type_error | type_error |
However, some of the exceptions provided by libpnicore do not have a proper counterpart in Python. In these cases new exceptions have been provided by pni.core which to which the original C++ exceptions get translated. These exceptions are
| C++ exception | Python exception |
|---|---|
| pni::core::file_error | pni.core.FileError |
| pni::core::shape_mismatch_error | pni.core.ShapeMismatchError |
| pni::core::size_mismatch_error | pni.core.SizeMismatcherror |
| pni::core::range_error | pni.core.RangeError |
| pni::core::iterator_error | pni.core.IteratorError |
| pni::core::cli_argument_error | pni.core.CliArgumentError |
| pni::core::cli_error | pni.core.CliError |
For more detailed information about under which conditions these exceptions are thrown, consult the libpnicore users guide.
Wraps the pni::core::cli_argument_error C++ exception. Thrown when a command line argument has an invalid value or is ill formatted.
Wraps the pni::core::cli_error C++ exception. Thrown in case of a general command line error.
Wraps the pni::core::file_error C++ exception. Thrown by operations from libpnicore and its related libraries in situations where a file cannot be opened or is in any other case faulty or access is denied.
Wraps the pni::core::iterator_error C++ exception. Thrown by the iterators provided by libpnicore in situations where something went wrong like an element cannot be dereferenced. Do not confuse this with the Python exception used to terminate iteration over a container!
Wraps the pni::core::range_error C++ exception. Thrown in situations where a numeric value must be within a particular range.
Wraps the pni::core::shape_mismatch_error C++ exception. This exception is typically thrown iperations where two array or array-like objects are involved which are supposed to have the same shape in order for the operation to succeed.
Wraps the pni::core::size_mismatch_error C++ exception. This exception is typically thrown by operations wher two containers involved are supposed to have the same size (number of elements) in order for the operation to succeed.
Raised when an instance tries to access an invalid NeXus object.
Raised in case of errors during link creation or access.
Raised in case of errors during object creation, movement, or copying.
Raised in case of a parser error during data input.
Property setting and getting an attribute name
This read/write property allows to set the attribute section of a NeXus path.
path = make_path("/:NXentry/:NXinstrument/NXdetector/data")
print(path)
#output /:NXentry/:NXinstrument/NXdetector/data
path.attribute = "units"
print(path)
#output /:NXentry/:NXinstrument/:NXdetector/data@units
Property returning the last element in the path
p = make_path("/:NXentry/:NXinstrument/:NXdetector/data")
print(p.back)
#output {'name':'data','base_class':''}
Property to set and get the filename section of the path
This read/write property can be used to set the filename section of a NeXus path.
p = make_path("/:NXentry/:NXinstrument/:NXdetector/data")
print(p)
#output /:NXentry/:NXinstrument/:NXdetector/data
p.filename = "test.nxs"
print(p)
#output test.nxs://:NXentry/:NXinstrument/:NXdetector/data
Property returning the first element in the path
p = make_path("/:NXentry/:NXinstrument/:NXdetector/data")
print(p.front)
#output {'name':'/','base_class':'NXroot'}
Remove last element from the object section
Remove first element from the object section of the path
Append element to the end of the object section
This method takes either two positional arguments
path.push_back("entry","NXentry")
Where the first one is the name and the optional second argument the base class of the path element.
Alternatively there are two keyword arguments
path.push_back(name="entry",base_class="NXentry")
which would have the same effect. Finally one can also use a single string to describe a new element
path.push_back("entry:NXentry")
path.push_back(":NXinstrument")
It must be noted that only a single element can be appended with push_back().
Prepends an element to a path
This method works like push_back() but prepends an element in front of the first one. The arguments work the same as for push_back().
Property returning the size of the path
The size of a path is the number of elements in the object section. In other words the number of elements without the optional filename and attribute.
Create a relative path
Makes the path old a relative path to parent. For this function to succeed both paths must satisfy two conditions
If any of these conditions is not satisfied a ValueError exception will be thrown.
parent = "/:NXentry/:NXinstrument"
old = "/:NXentry/:NXinstrument/:NXdetector/data"
rel_path = make_relative(parent,old)
print(rel_path)
#output: :NXdetector/data
| Parameters: |
|
|---|---|
| Returns: | path refering to the same object as old but relative to parent |
| Return type: | str |
| Raises ValueError: | |
old and parent do not satifisy the above conditions |
|
Create a path object from a string
Create a new path object from its string representation.
| Parameters: | path_str (str) – string representation of the path |
|---|---|
| Returns: | new path object |
| Return type: | instance of nxpath |
- C++ signature :
- bool match(std::string,std::string)
match( (nxpath)arg1, (nxpath)arg2) -> bool :
- C++ signature :
- bool match(pni::io::nx::nxpath,pni::io::nx::nxpath)
Checks if an element is the root element
Returns true if the element passed as the argument is the root element of the NeXus tree. This is the case if the element dictionary has a key name of with value ‘/’ and a key base_class with value ‘NXroot’.
| Parameters: | path_element (dict) – the element dictionary |
|---|---|
| Returns: | true if the element describes the root element |
| Return type: | bool |
True if the path is empty
An instance of nxpath is considered empty if * it has no file-section * no attribute section * and no object section
If all this conditions are holding this function will return true.
| Parameters: | path (nxpath) – the path to check |
|---|---|
| Returns: | true if the path is empty, false otherwise |
| Return type: | bool |
True if the element has a name
Returns true if the element dictionary passed has a non-empty name key.
| Parameters: | path_element (dict) – the path element to check |
|---|---|
| Returns: | true if the name key has a non-empty string value |
| Return type: | bool |
True if the element has a non-empty class
| Parameters: | path_element (dict) – the path element to check |
|---|---|
| Returns: | true if the base_class key has a non-empty string value |
| Return type: | bool |
Returns true if the path is absolute
If the first element in the object section is the root element the path is is considered to be absolute.
| Parameters: | path (nxpath) – path to check for absolutness |
|---|---|
| Returns: | true if the path is absolut, false otherwise |
| Return type: | bool |
Closes the file.
Other objects belonging to this file residing within the same scope must be closed explicitely if the file should be reopened!
Flush the content of the file. This method writes all the changes made to the file to disk.
Property for object status
If True the object is a valid NeXus object, False otherwise.
Property for file status
If True the file is in read only mode.
create a new NeXus file
This function creates a new NeXus file. All data will go o this file. If the file already exists the pni.core.FileError exception will be thrown. In order to overwrite an existing file of equal name set the overwrite flag to True.
| Parameters: |
|
|---|---|
| Returns: | new file |
| Return type: | instance of nxfile |
:raises pni.core.FileError: in case of problems
create a split file
Create a new file which is splitted into subfiles of a given size. unlike for the create_file function the file name argument is a C-style format string which includes a running index for the individual files.
A valid filename could look like this data_file.%05i.nxs which would lead to a series of files named
data_file.00001.nxs
data_file.00002.nxs
data_file.00003.nxs
| Parameters: |
|
|---|---|
| Returns: | a new instance of nxfile |
| Return type: | instance of nxfile |
:raises pni.core.FileError: in case of problems
Opens an existing Nexus file.
fname can either be a simple path to a file or a C-style format string as described for py:create_files(). In the later case a series of NeXus files is opened.
| Parameters: |
|
|---|---|
| Returns: | new file |
| Return type: | instance of nxfile |
Read only property with the attribute manager for this group
Close this group
Create a new field
Create a new field below this group.
| Parameters: |
|
|---|---|
| Returns: | instance of a new field |
| Return type: | instance of nxfield |
Checks if the object determined by ‘name’ exists
‘name’ can be either an absolute or relative path. If the object identified by ‘name’ exists the method returns true, false otherwise.
| Parameters: | name (str) – name of the object to check |
|---|---|
| Returns: | True if the object exists, False otherwise |
| Return type: | bool |
Read only property returning the name of the file the group belongs to
Read only property returning True if this instance is a valid NeXus object
Read only property returning the name of the group
Opens an existing object
The object is identified by its name (path).
| Parameters: | n (str) – name (path) to the object to open |
|---|---|
| Returns: | the requested child object |
| Return type: | either an instance of nxfield, nxgroup, or nxlink |
| Raises KeyError: | |
| if the child could not be found | |
Read only property returning the parent group of this group
Read only property returning the NeXus path for this group
Read only property returning a recursive iterator for this group
Read only property returing the number of links below this group
Read only property with the attribute manager for this field
Close this field
Read only property providing the datatype of the field as numpy type code
Read only property returning the name of the file the field belongs to
Grow the field
Grow the field along dimension ‘dim’ by ‘ext’ elements.
| Parameters: |
|
|---|
Read only property returning True if this instance is a valid NeXus object
Read only property returning the name of the field
Read only property returning the parent group of this field
Read only property returning the NeXus path for this field
Read data from field
Read all data stored in a field and return it as a numpy array of appropriatetype.
| Returns: | data stored in the field |
|---|---|
| Return type: | numpy array |
Read only property providing the shape of the field as tuple
Read only property returing the number of elements this field holds
Write data to field
Write all data stored in the data argument to the field. data must be a numpy array of appropriate shape. The type of the the numpy array must be convertible to the type of the field.
| Parameters: | data (numpy.ndarray) – the data which should be written to disk |
|---|
:raises ShapeMismatchError: if the shape of the field does not match :raises SizeMismatchError: if the size of field and data do not match
Class method to close an open attribute.
Read only property providing the data-type of the attribute as numpy type-code
Read only property returning the name of the file the attribute belongs to
Read only property returning True if the attribute is a valid NeXus object
A read only property providing the name of the attribute as a string.
Read only property returning the parent object of this attribute
Read only property returning the NeXus path for this attribute
Read entire attribute
Reads all data from the attribute and returns it either as a single scalar value or as an instance of a numpy array.
| Returns: | attribute data |
|---|---|
| Return type: | instance of numpy.ndarray or a scalar native Python type |
Read only property providing the shape of the attribute as tuple.
Read only property returing the number of elements this attribute holds
Write attribute data
Writes entire attribute data to disk. The argument passed to this method is either a single scalar object or an instance of a numpy array.
| Parameters: | data (numpy.ndarray) – attribute data to write |
|---|
read/write property to set and get the compression rate as an integer between 0 and 9
read/write boolean property to switch shuffeling on and of (True or False)
read only property returning the name of the file the links belongs to
read only property returning True if the link is valid
read only property returning the name of the link
read only property returning the parent object of the link
Return object
Return the object referenced by this link. If the link cannot be resolved an instance of nxlink is returned.
| Returns: | referenced object |
|---|---|
| Return type: | instance of nxlink, nxgroup, or nxfield |
read only property returning the status of the link
read only property returning the path jto the links target
read only property returning the type of the link
Returns the size of an object
The semantics of size depends on the object. In the case of a group the number of children is returned. For attributes and fields the number of elements. :param object object: instance of nxattribute, nxfield, or nxgroup :return: number of elements or children :rtype: long
Returns the name of an object
| Parameters: | object (object) – instance of nxattribute, nxlink, nxfield, or nxgroup |
|---|---|
| Returns: | the objects name |
| Return type: | str |
Returns the rank of a field or attribute
Returns the number of dimensions a field or attribute has.
| Parameters: | object (object) – instance of nxattribute or nxfield |
|---|---|
| Returns: | the rank of the object |
| Return type: | long |
Return the unit of a field
Convenience function reading the units attribute of a field and returns its value.
| Parameters: | field (nxfield) – the field from which to read the unit |
|---|---|
| Returns: | value of the units attribute |
| Return type: | str |
Read NXclass attribute from group
Convenience function reading the NX_class attribute of a group and returns and returns its value.
| Parameters: | group (object) – group from which to read NX_class |
|---|---|
| Returns: | value of NX_class |
| Return type: | str |
Get object by path
Return an object determined by its path from a parent. The path can either be relative to the parent or absolute. In the latter case the parent will only be used to obtain the root group.
| Parameters: |
|
|---|---|
| Returns: | the requested object |
| Return type: | an attribute, field, group, or link instance |
Get object by path
Return an object determined by its path from a parent. The path can either be relative to the parent or absolute. In the latter case the parent will only be used to obtain the root group.
| Parameters: |
|
|---|---|
| Returns: | the requested object |
| Return type: | an attribute, field, group, or link instance |
Return the NeXus path of an object
Return the full NeXus path of an object.
| Parameters: | object (object) – instance of nxfield, nxattribute, nxgroup, or nxlink |
|---|---|
| Returns: | full NeXus path |
| Return type: | str |
Create a new link
Use this function to create new soft and external links (hard links are only created during object creation). The first positional argument of this function is the target for the link. This can be either * a relative (to the parent) or absolut path to the target * or an instance of nxfield of nxgroup
| Parameters: |
|
|---|
Returns a list of links
Returns a list of links referencing the direct members of the parent object.
| Parameters: | parent (nxgroup) – The parent object for which to obtain the link list |
|---|---|
| Returns: | list of links |
| Return type: | list with instances of nxlink |
Returns a list of links
Like get_links() but decendes recursively through all children of the parent group.
| Parameters: | parent (nxgroup) – the parent object for which to obtain the link list |
|---|---|
| Returns: | list of links below parent |
| Return type: | list with instances of nxlink |