# Declarative Python
[](https://api.reuse.software/info/git.fsfe.org/reuse/api)
Collection of decorators and base classes to allow a declarative style of programming. The
underlying philosophy can be described as "init considered harmful". Instead, object attributes
are constructed from decorator functions and then stored. This is essentially like the @property
decorator, but @declarative.mproperty additionally _stores_ (memoizes) the result. Unlike the @property
builtin, @declarative.mproperty can take an argument, providing convenient parameterization and transformation
of inputs.
For classes inheriting declarative.OverridableObject, the @declarative.dproperty attribute can be used
and all properties will be called/accessed within the __init__ constructor to ensure construction. This allows
objects to register with other objects and is convenient for event-loop reactor programming.
The Argparse sub-library allows the user to create quick command-line interfaces to create and run methods in declarative fashion.
The technique of access->construction means that the dependencies between class attributes are resolved
automatically. During the construction of each attribute, any required attributes are accessed and therefore
constructed if they haven't already been.
The price for the convenience is that construction becomes implicit and recursive. The wrappers in this library
do some error checking to aid with this and to properly report AttributeError. Code also ends up somewhat more
verbose with the decorator boilerplate.
## Quick Example
```python
import declarative
class Child(object):
id = None
class Parent(object):
@declarative.mproperty
def child_registry(self):
return set()
@declarative.mproperty
def c1(self):
print("made Parent.c1")
child = Child()
child.id = 1
self.child_registry.add(child)
return child
@declarative.mproperty
def c2(self):
print("made Parent.c2")
child = Child()
child.id = 2
self.child_registry.add(child)
return child
parent = Parent()
parent.c1
#>> made Parent.c1
parent.c2
#>> made Parent.c2
print(parent.child_registry)
```
Ok, so now as the child object attributes are accessed, they are also registered.
## More automatic Example
```python
import declarative
class Child(declarative.OverridableObject):
id = None
class Parent(declarative.OverridableObject):
@declarative.mproperty
def child_registry(self):
return set()
@declarative.dproperty
def c1(self, val = None):
if val is None:
child = Child(
id = 1,
)
print("made Parent.c1")
else:
print("Using outside c1")
child = val
self.child_registry.add(child)
return child
@declarative.dproperty
def c2(self):
child = Child(
id = 2,
)
print("made Parent.c2")
self.child_registry.add(child)
return child
@declarative.dproperty
def c2b(self):
child = Child(
id = self.c2.id + 0.5
)
print("made Parent.c2b")
self.child_registry.add(child)
return child
parent = Parent()
#>> made Parent.c2
#>> made Parent.c2b
#>> made Parent.c1
print(parent.child_registry)
```
Now the registry is filled instantly.
Alternatively, c1 for this object can be replaced.
```
parent = Parent(
c1 = Child(id = 8)
)
#>> made Parent.c2
#>> made Parent.c2b
#>> using outside c1
print(parent.child_registry)
```
No __init__ function!
## Numerical Usage
This technique can be applied for memoized numerical results, particularly when you might
want to canonicalize the inputs to use a numpy representation.
```python
import declarative
class MultiFunction(declarative.OverridableObject):
@declarative.dproperty
def input_A(self, val):
#not providing a default makes them required keyword arguments
#during construction
return numpy.asarray(val)
@declarative.dproperty
def input_B(self, val):
return numpy.asarray(val)
@declarative.mproperty
def output_A(self):
#note usage of mproperty. This will only be computed if accessed, not at construction
return self.input_A + self.input_B
@declarative.mproperty
def output_B(self):
#note the use of incremental computing into output_A
return self.input_A * self.input_B - self.output_A
data = MultiFunction(
input_A = [1,2,3],
input_B = [4,5,6],
)
print(data.output_A)
```
## Additional Features
### Argparse interface
Mentioned above. Some additional annotations and run methods can allow objects to be called and accessed from the command line, without a special interface while providing improved composition of declarative programming.
### Bunches
These are dictionary objects that also allow indexing through the '.' attribute access operator. Other libraries provide these, but the ones included here are
* Bunch - just a dictionary wrapper. It also wraps any dictionary's that are stored to provide a consistent interface.
* DeepBunch - Allows nested access without construction of intermediate dictionary's. Extremely convenient for configuration management of hierarchical systems.
* HDFDeepBunch - DeepBunch adapted so that the underlying storage are HDF5 data groups using the h5py library. Automatically converts to/from numpy arrays and unwraps values. DeepBunch's containing compatible numbers/arrays can be directly embedded into hdf. This allows configuration storage with datasets.
See the Bunch page for more.
### Relays and Callbacks
A number of objects are provided for reactor programming. These are RelayValue and RelayBool which store values and run callbacks upon their change. This is similar Qt's signal/socket programming but lightweight for python.
### Substrate System
This is the culmination of the declarative techniques to hierarchical simulation and modeling. Child objects automatically embed into parent objects and gain access to nonlocal data and registration interfaces. It invokes considerably more "magic" than this library typically need. Currently used by the python physics/controls simulation software openLoop.
## Development
This library was developed in initial form to generate the Control System and interfaces of the Holometer experiment at Fermilab. The underlying technology for that is the EPICS distributed experimental control library (developed at Argonne).
RelayBool and RelayValue objects were bound to EPICS variables using the declarative construction methods of this library. Further logic cross-linked variables and interfaced to hardware. Bunches were used for configuration management. HDFDeepBunch was used for data analysis.
## Related Documentation
Using multiple inheritance and mixins becomes very simple with this style of programming, but super is often needed, but forces the use of keyword arguments. Since this library forces them anyway, this site details other considerations for using super:
* https://fuhm.net/super-harmful/
Raw data
{
"_id": null,
"home_page": "https://github.com/wieldphysics/wield-declarative",
"name": "wield.declarative",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "",
"author": "Lee McCuller",
"author_email": "mcculler@caltech.edu",
"download_url": "https://files.pythonhosted.org/packages/e1/37/d8699e740584a8e71d46530db9767c2c0d3dd42e7af61335bea6b29637aa/wield.declarative-1.5.1.tar.gz",
"platform": null,
"description": "# Declarative Python\n[](https://api.reuse.software/info/git.fsfe.org/reuse/api)\n\nCollection of decorators and base classes to allow a declarative style of programming. The \nunderlying philosophy can be described as \"init considered harmful\". Instead, object attributes\nare constructed from decorator functions and then stored. This is essentially like the @property\ndecorator, but @declarative.mproperty additionally _stores_ (memoizes) the result. Unlike the @property\nbuiltin, @declarative.mproperty can take an argument, providing convenient parameterization and transformation\nof inputs.\n\nFor classes inheriting declarative.OverridableObject, the @declarative.dproperty attribute can be used\nand all properties will be called/accessed within the __init__ constructor to ensure construction. This allows\nobjects to register with other objects and is convenient for event-loop reactor programming.\n\nThe Argparse sub-library allows the user to create quick command-line interfaces to create and run methods in declarative fashion.\n\nThe technique of access->construction means that the dependencies between class attributes are resolved\nautomatically. During the construction of each attribute, any required attributes are accessed and therefore\nconstructed if they haven't already been.\n\nThe price for the convenience is that construction becomes implicit and recursive. The wrappers in this library\ndo some error checking to aid with this and to properly report AttributeError. Code also ends up somewhat more\nverbose with the decorator boilerplate.\n\n## Quick Example\n\n```python\nimport declarative\n\nclass Child(object):\n id = None\n\nclass Parent(object):\n @declarative.mproperty\n def child_registry(self):\n return set()\n\n @declarative.mproperty\n def c1(self):\n print(\"made Parent.c1\")\n child = Child()\n child.id = 1\n self.child_registry.add(child)\n return child\n\n @declarative.mproperty\n def c2(self):\n print(\"made Parent.c2\")\n child = Child()\n child.id = 2\n self.child_registry.add(child)\n return child\n\nparent = Parent()\nparent.c1\n#>> made Parent.c1\nparent.c2\n#>> made Parent.c2\nprint(parent.child_registry)\n```\n\nOk, so now as the child object attributes are accessed, they are also registered.\n\n## More automatic Example\n\n```python\nimport declarative\n\nclass Child(declarative.OverridableObject):\n id = None\n\nclass Parent(declarative.OverridableObject):\n @declarative.mproperty\n def child_registry(self):\n return set()\n\n @declarative.dproperty\n def c1(self, val = None):\n if val is None:\n child = Child(\n id = 1,\n )\n print(\"made Parent.c1\")\n else:\n print(\"Using outside c1\")\n child = val\n \n self.child_registry.add(child)\n return child\n\n @declarative.dproperty\n def c2(self):\n child = Child(\n id = 2,\n )\n print(\"made Parent.c2\")\n self.child_registry.add(child)\n return child\n\n @declarative.dproperty\n def c2b(self):\n child = Child(\n id = self.c2.id + 0.5\n )\n print(\"made Parent.c2b\")\n self.child_registry.add(child)\n return child\n\nparent = Parent()\n#>> made Parent.c2\n#>> made Parent.c2b\n#>> made Parent.c1\nprint(parent.child_registry)\n```\n\nNow the registry is filled instantly.\n\nAlternatively, c1 for this object can be replaced.\n\n\n```\nparent = Parent(\n c1 = Child(id = 8)\n)\n#>> made Parent.c2\n#>> made Parent.c2b\n#>> using outside c1\nprint(parent.child_registry)\n```\n\nNo __init__ function! \n\n## Numerical Usage\n\nThis technique can be applied for memoized numerical results, particularly when you might \nwant to canonicalize the inputs to use a numpy representation.\n\n```python\nimport declarative\n\nclass MultiFunction(declarative.OverridableObject):\n @declarative.dproperty\n def input_A(self, val):\n #not providing a default makes them required keyword arguments\n #during construction\n return numpy.asarray(val)\n\n @declarative.dproperty\n def input_B(self, val):\n return numpy.asarray(val)\n\n @declarative.mproperty\n def output_A(self):\n #note usage of mproperty. This will only be computed if accessed, not at construction\n return self.input_A + self.input_B\n\n @declarative.mproperty\n def output_B(self):\n #note the use of incremental computing into output_A\n return self.input_A * self.input_B - self.output_A\n\ndata = MultiFunction(\n input_A = [1,2,3],\n input_B = [4,5,6],\n)\nprint(data.output_A)\n```\n\n## Additional Features\n\n### Argparse interface\nMentioned above. Some additional annotations and run methods can allow objects to be called and accessed from the command line, without a special interface while providing improved composition of declarative programming.\n\n### Bunches\nThese are dictionary objects that also allow indexing through the '.' attribute access operator. Other libraries provide these, but the ones included here are\n\n* Bunch - just a dictionary wrapper. It also wraps any dictionary's that are stored to provide a consistent interface.\n* DeepBunch - Allows nested access without construction of intermediate dictionary's. Extremely convenient for configuration management of hierarchical systems.\n* HDFDeepBunch - DeepBunch adapted so that the underlying storage are HDF5 data groups using the h5py library. Automatically converts to/from numpy arrays and unwraps values. DeepBunch's containing compatible numbers/arrays can be directly embedded into hdf. This allows configuration storage with datasets.\n\nSee the Bunch page for more.\n\n### Relays and Callbacks\nA number of objects are provided for reactor programming. These are RelayValue and RelayBool which store values and run callbacks upon their change. This is similar Qt's signal/socket programming but lightweight for python.\n\n### Substrate System\nThis is the culmination of the declarative techniques to hierarchical simulation and modeling. Child objects automatically embed into parent objects and gain access to nonlocal data and registration interfaces. It invokes considerably more \"magic\" than this library typically need. Currently used by the python physics/controls simulation software openLoop.\n\n## Development\nThis library was developed in initial form to generate the Control System and interfaces of the Holometer experiment at Fermilab. The underlying technology for that is the EPICS distributed experimental control library (developed at Argonne). \n\nRelayBool and RelayValue objects were bound to EPICS variables using the declarative construction methods of this library. Further logic cross-linked variables and interfaced to hardware. Bunches were used for configuration management. HDFDeepBunch was used for data analysis.\n\n\n## Related Documentation\nUsing multiple inheritance and mixins becomes very simple with this style of programming, but super is often needed, but forces the use of keyword arguments. Since this library forces them anyway, this site details other considerations for using super:\n * https://fuhm.net/super-harmful/\n \n \n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "Base classes and methods for declarative object instantiation",
"version": "1.5.1",
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "2bf829089318d719d544793d9923ab9c196170b5fa4fc1a4797e78ffeadc1ae8",
"md5": "7cc8485c45621d45754433c9085cfc52",
"sha256": "bbe73c9a504a2fb4c39336ef150b116a5009478c02788984fce51b5cb9f3c4df"
},
"downloads": -1,
"filename": "wield.declarative-1.5.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "7cc8485c45621d45754433c9085cfc52",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 42877,
"upload_time": "2023-04-15T23:37:31",
"upload_time_iso_8601": "2023-04-15T23:37:31.896941Z",
"url": "https://files.pythonhosted.org/packages/2b/f8/29089318d719d544793d9923ab9c196170b5fa4fc1a4797e78ffeadc1ae8/wield.declarative-1.5.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "e137d8699e740584a8e71d46530db9767c2c0d3dd42e7af61335bea6b29637aa",
"md5": "d392ca24441b72a512238206bf53127f",
"sha256": "f6e81ca0a61c890dd2304677923051b49d577c74e7ee9e73f8a9a78509eda611"
},
"downloads": -1,
"filename": "wield.declarative-1.5.1.tar.gz",
"has_sig": false,
"md5_digest": "d392ca24441b72a512238206bf53127f",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 32267,
"upload_time": "2023-04-15T23:37:34",
"upload_time_iso_8601": "2023-04-15T23:37:34.016639Z",
"url": "https://files.pythonhosted.org/packages/e1/37/d8699e740584a8e71d46530db9767c2c0d3dd42e7af61335bea6b29637aa/wield.declarative-1.5.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-04-15 23:37:34",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "wieldphysics",
"github_project": "wield-declarative",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "wield.declarative"
}
JSON
