Represent type-checked specifications as Python classes and incrementally build them.
Project description
- Documentation: https://matthewwardrop.github.io/spec-classes
- Source Code: https://github.com/matthewwardrop/spec-classes
- Issue tracker: https://github.com/matthewwardrop/spec-classes/issues
Introduction
spec_classes
is a stand-alone (but largely interoperable) generalization
of the standard library's dataclass
decorator. It adds, among other things:
type-checking, rich field preparation, and convenient copy-on-write mutation
wrappers. Spec-class definitions are Pythonic, simple, and concise.
This library is especially useful in contexts where run-time validation and instant feedback is desirable, and/or where correctness is valued over performance. With that said, we do try to keep spec-classes performant (see performance details).
Philosophy
It should be hard for users to do the wrong thing. spec_classes
is
designed to help end-users interact with, mutate, and assemble (especially in ad
hoc contexts like notebooks) potentially large libraries of data classes without
fear of breaking things. Operations on data classes should be atomic (operations
should never be partially committed), validated (types should match, etc.), and
provide instant helpful feedback when the user makes a mistake.
We don't own your class. spec_classes
never overrides local
pre-existing methods, and doesn't add any metaclasses or parents. If you
decorate a class with @spec_class
, spec classes will add (if you have not
already) some dunder magic methods (like __init__
,__setattr__
, etc.), and
some helper methods... but that's it. Spec classes are, at the end of the day,
just regular classes pre-loaded with useful methods that you didn't have to
write yourself.
Copy-on-write by default. One of the dangers with using class instances as
specification is that if they are mutated in one context, they are mutated for
all contexts. Spec classes does not prevent (by default) local mutations of
class instances (you can still do my_spec.foo = 'bar'
); but all helper methods
return a mutated copy by default. For example, my_spec.with_foo('bar')
will
not be the same instance as my_spec
, and so these methods are always safe to
use.
Be consistent. All helper methods added by spec_classes
exist within well
defined namespaces; that is: with_<attr>
, transform_<attr>
, etc.; and each
class of methods has the same naming conventions for arguments and provides
complete inline documentation. This makes it easy for users to figure out how to
use the methods, to override these methods and/or to add new methods that do not
collide.
Minimize Surprise. The behavior of spec classes almost always matches that of base Python classes where functionality overlaps, and should always be intuitive otherwise (e.g. when type-checking is violated).
Performance is important. Although performance is not the primary goal of
spec_classes
, given the targeted feature-set, the overhead introduced should
be as small as possible.
Example
from spec_classes import spec_class
@spec_class
class Rectangle:
width: float
height: float
color: str
@property
def area(self):
return self.width * self.height
rect = Rectangle()
rect # Rectangle(width=MISSING, height=MISSING, color=MISSING)
rect.update(width=10., height=12.).with_color("red") # Rectangle(width=10.0, height=12.0, color='red')
Rectangle(width=10., height=10.).area # 100.0
rect.with_width('invalid') # TypeError: Attempt to set `Rectangle.width` with an invalid type [got `'invalid'`; expecting `float`].
For more details on usage, refer to the documentation.
Installation
Spec classes can be installed via pip
or conda
.
To install via pip
you can use:
pip install spec-classes
To install via conda
you can use:
conda install spec-classes
You can verify that the installation was successful by printing the version of
spec-classes
that was installed:
python -c "import spec_classes; print(spec_classes.__version__)"
Related projects and prior art
spec_classes
takes a more opinionated stance than most libraries in this space
on exactly how data-classes should be built and mutated. Nevertheless, there are
excellent pre-existing alternatives to spec-classes for those looking for
something lighter-weight. In particular, you could consider:
- typeguard: A utility library for run-time type-checking functions, methods and classes.
- pytypes: Another utility library for run-time type-checking functions, methods and classes.
- pydantic: A light-weight data parsing and validation library that also uses type hints.
- attrs: A library that provides a super-set of the functionality of Python's data-class, but still adds no run-time overhead (no type-checking, extra helper-methods, etc).
There are many other libraries in the business of mapping and validating transformations from JSON to Python classes, but these are somewhat orthogonal to the aims of this project (which is to make Python classes themselves pleasant to use), and so they are not included here.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for spec_classes-1.5.2-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 452b438eaa6894ce375661a39e8b14bb9fa8cb79f36cdb721ce4ec54fc7ec93b |
|
MD5 | e0f700f76671e2209242bef527b2b112 |
|
BLAKE2b-256 | 0f1f7b5031734110d2fe0c80b51acc3268044724904871d90273348bec0a3034 |