<commit_before>A Python Wrapper for Stratisd D-Bus Calls
=========================================

This library is not stable and is not intended for public use. Not only may
it change without notice, but it may also be entirely removed without notice.

Introduction
------------
This library is a simple wrapper for use by a client of the stratisd D-Bus API.
It is built on top of the dbus-python library. It ensures that the values
placed on the dbus by the client conform to the expected types.

Stratisd explicitly exposes the value of constants, like error codes, on the
dbus. This library has a facility for reading and cacheing these values,
so that clients can refer to these constants by name, rather than by their
value. This makes clients more robust to changes in the stratisd implementation,
i.e., reordering of the constants resulting in different numeric values for
their names. This also makes the stratisd implementation more easily
extensible, since new values can be added without forcing any changes in the
client. The class corresponding to a particular list of constants is
obtained by invoking the get_object() method of the corresponding Gen class. ::

    >>> STRATISD_ERRORS = StratisdErrorsGen.get_object()

The constants can then be accessed as attributes by name: ::

    >>> STRATISD_ERRORS.OK

It is up to the client to cache the generated class at whatever level is
appropriate.

Stratisd also implements certain special interfaces for the various objects
it exposes on the dbus. These are implemented as classes, which expose the
methods and properties of the interface as static attributes. For example, ::

    >>> Manager.GetPoolObjectPath(proxy_object, "apool")

invokes the GetPoolObjectPath method for the Manager interface on the proxy
object, passing as an argument the name of the pool. ::

    >>> Dev.Properties.Size(proxy_object)

obtains the value of the Size property of the Dev interface for proxy_object.
The arguments placed on the D-Bus for a given method are martialed according
to cached information about stratisd's input specification for that method
into the correct dbus-python types.

This library does not have its own set of exceptions. Instead, it raises
ValueError exceptions, or allows internal errors to propagate. None of these
exceptions can be considered part of its interface.

Testing
-------
The source code of this library is simple and very short. Some tests exist
to verify that certain class-invariants are maintained.

The bulk of the tests in the repository test the stratisd engine via the
D-Bus API. They test basic functionality and behavior of the various D-Bus
methods and ensure that the values returned conform to their signature
specification.

To run the existing D-Bus tests, ensure that your PYTHONPATH includes the
src directory and then: ::

    > make dbus-tests

Contributing
------------
This is the rare library where the tests are actually more important than
the source code. Issues suggesting tests or pull requests that extend the
existing test suite are welcome.
<commit_msg>Update README to include information on setting STRATISD<commit_after>A Python Wrapper for Stratisd D-Bus Calls
=========================================

This library is not stable and is not intended for public use. Not only may
it change without notice, but it may also be entirely removed without notice.

Introduction
------------
This library is a simple wrapper for use by a client of the stratisd D-Bus API.
It is built on top of the dbus-python library. It ensures that the values
placed on the dbus by the client conform to the expected types.

Stratisd explicitly exposes the value of constants, like error codes, on the
dbus. This library has a facility for reading and cacheing these values,
so that clients can refer to these constants by name, rather than by their
value. This makes clients more robust to changes in the stratisd implementation,
i.e., reordering of the constants resulting in different numeric values for
their names. This also makes the stratisd implementation more easily
extensible, since new values can be added without forcing any changes in the
client. The class corresponding to a particular list of constants is
obtained by invoking the get_object() method of the corresponding Gen class. ::

    >>> STRATISD_ERRORS = StratisdErrorsGen.get_object()

The constants can then be accessed as attributes by name: ::

    >>> STRATISD_ERRORS.OK

It is up to the client to cache the generated class at whatever level is
appropriate.

Stratisd also implements certain special interfaces for the various objects
it exposes on the dbus. These are implemented as classes, which expose the
methods and properties of the interface as static attributes. For example, ::

    >>> Manager.GetPoolObjectPath(proxy_object, "apool")

invokes the GetPoolObjectPath method for the Manager interface on the proxy
object, passing as an argument the name of the pool. ::

    >>> Dev.Properties.Size(proxy_object)

obtains the value of the Size property of the Dev interface for proxy_object.
The arguments placed on the D-Bus for a given method are martialed according
to cached information about stratisd's input specification for that method
into the correct dbus-python types.

This library does not have its own set of exceptions. Instead, it raises
ValueError exceptions, or allows internal errors to propagate. None of these
exceptions can be considered part of its interface.

Testing
-------
The source code of this library is simple and very short. Some tests exist
to verify that certain class-invariants are maintained.

The bulk of the tests in the repository test the stratisd engine via the
D-Bus API. They test basic functionality and behavior of the various D-Bus
methods and ensure that the values returned conform to their signature
specification.

To run the existing D-Bus tests, ensure that your PYTHONPATH includes the
src directory, set the environment variable STRATISD, to the location of your
Stratis executable, and: ::

    > make dbus-tests

Contributing
------------
This is the rare library where the tests are actually more important than
the source code. Issues suggesting tests or pull requests that extend the
existing test suite are welcome.

{'fraction_non_alphanumeric': 0.054385964912280704, 'fraction_numerical': 0.0, 'mean_word_length': 4.327952421410365, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 29, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '5465595', 'n_tokens_mistral': 1488, 'n_tokens_neox': 1431, 'n_words': 924}