diff options
Diffstat (limited to 'python-interface-meta.spec')
| -rw-r--r-- | python-interface-meta.spec | 555 |
1 files changed, 555 insertions, 0 deletions
diff --git a/python-interface-meta.spec b/python-interface-meta.spec new file mode 100644 index 0000000..ac381c9 --- /dev/null +++ b/python-interface-meta.spec @@ -0,0 +1,555 @@ +%global _empty_manifest_terminate_build 0 +Name: python-interface-meta +Version: 1.3.0 +Release: 1 +Summary: `interface_meta` provides a convenient way to expose an extensible API with enforced method signatures and consistent documentation. +License: MIT +URL: https://pypi.org/project/interface-meta/ +Source0: https://mirrors.nju.edu.cn/pypi/web/packages/4d/75/10526292b332f3479c246750a96f6ec11a28e297839a9c25583b2aadc119/interface_meta-1.3.0.tar.gz +BuildArch: noarch + + +%description +# InterfaceMeta + +[](https://pypi.org/project/interface_meta/) + + +[](https://github.com/matthewwardrop/interface_meta/actions?query=workflow%3A%22Run+Tox+Tests%22) +[](https://codecov.io/gh/matthewwardrop/interface_meta) +[](https://github.com/psf/black) + +`interface_meta` provides a convenient way to expose an extensible API with +enforced method signatures and consistent documentation. + +- **Documentation:** See below (full documentation will come at some point). +- **Source:** https://github.com/matthewwardrop/interface_meta +- **Bug reports:** https://github.com/matthewwardrop/interface_meta/issues + +## Overview + +This library has been extracted (with some modifications) from +[`omniduct`](https://github.com/airbnb/omniduct), a library also principally +written by this author, where it was central to the extensible plugin +architecture. It places an emphasis on the functionality required to create a +well-documented extensible plugin system, whereby the act of subclassing is +sufficient to register the plugin and ensure compliance to the parent API. As +such, this library boasts the following features: + +- All subclasses of an interface must conform to the parent's API. +- Hierarchical runtime property existence and method signature checking. Methods + are permitted to add additional *optional* arguments, but otherwise must + conform to the API of their parent class (which themselves may have extended + the API of the interface). +- Subclass definition time hooks (e.g. for registration of subclasses into a + library of plugins, etc). +- Optional requirement for methods in subclasses to explicity decorate methods + with an `override` decorator when replacing methods on an interface, making + it clearer as to when a class is introducing new methods versus replacing + those that form the part of the interface API. +- Generation of clear docstrings on implementations that stitches together the + base interface documentation with any downstream extensions and quirks. +- Support for extracting the quirks documentation for a method from other method + docstrings, in the event that subclass implementations are done in an internal + method. +- Compatibility with ABCMeta from the standard library. + +## Example code + +```python +from abc import abstractmethod, abstractproperty +from interface_meta import InterfaceMeta, override, quirk_docs + +class MyInterface(metaclass=InterfaceMeta): + """ + An example interface. + """ + + INTERFACE_EXPLICIT_OVERRIDES = True + INTERFACE_RAISE_ON_VIOLATION = False + INTERFACE_SKIPPED_NAMES = {'__init__'} + + def __init__(self): + """ + MyInterface constructor. + """ + pass + + @abstractproperty + def name(self): + """ + The name of this interface. + """ + pass + + @quirk_docs(method='_do_stuff') + def do_stuff(self, a, b, c=1): + """ + Do things with the parameters. + """ + return self._do_stuff(a, b, c) + + @abstractmethod + def _do_stuff(self, a, b, c): + pass + +class MyImplementation(MyInterface): + """ + This implementation of the example interface works nicely. + """ + + @quirk_docs(method='_init', mro=False) + def __init__(self, a): + """ + MyImplementation constructor. + """ + self._init(a) + + def _init(self, a): + """ + In this instance, we do nothing with a. + """ + pass + + @property + @override + def name(self): + return "Peter" + + @override + def _do_stuff(self, a, b, c): + """ + In this implementation, we sum the parameters. + """ + return a + b + c +``` + +Running `help(MyImplementation)` reveals how the documentation is generated: + +```python +class MyImplementation(MyInterface) + | This implementation of the example interface works nicely. + | + | Method resolution order: + | MyImplementation + | MyInterface + | builtins.object + | + | Methods defined here: + | + | __init__(self, a) + | MyImplementation constructor. + | + | In this instance, we do nothing with a. + | + | do_stuff(self, a, b, c=1) + | Do things with the parameters. + | + | MyImplementation Quirks: + | In this implementation, we sum the parameters. + ... +``` + +## Related projects and prior art + +This library is released into an already crowded space, and the author would +like to recognise some of the already wonderful work done by others. The primary +difference between this and other libraries is typically these other libraries +focus more on abstracting interface definitions and compliance, and less on the +documentation and plugin registration work. While this work overlaps with these +projects, its approach is sufficiently different (in the author's opinion) +to warrant a separate library. + +- [`pure_interface`](https://github.com/seequent/pure_interface) +- [`python-interface`](https://github.com/ssanderson/interface) + +`python-interface` has an emphasis on ensuring that implementations of various +interfaces *strictly* adhere to the methods and properties associated with +the interface, and that helpful errors are raised when this is violated. + +By +comparison this library focusses on functional comformance to parent classes, +whereby methods on subclasses are allowed to include additional parameters. It +also focusses on ensuring that documentation for such quirks in method signatures are correctly composed into the final documentation rendered for that method. + + +%package -n python3-interface-meta +Summary: `interface_meta` provides a convenient way to expose an extensible API with enforced method signatures and consistent documentation. +Provides: python-interface-meta +BuildRequires: python3-devel +BuildRequires: python3-setuptools +BuildRequires: python3-pip +%description -n python3-interface-meta +# InterfaceMeta + +[](https://pypi.org/project/interface_meta/) + + +[](https://github.com/matthewwardrop/interface_meta/actions?query=workflow%3A%22Run+Tox+Tests%22) +[](https://codecov.io/gh/matthewwardrop/interface_meta) +[](https://github.com/psf/black) + +`interface_meta` provides a convenient way to expose an extensible API with +enforced method signatures and consistent documentation. + +- **Documentation:** See below (full documentation will come at some point). +- **Source:** https://github.com/matthewwardrop/interface_meta +- **Bug reports:** https://github.com/matthewwardrop/interface_meta/issues + +## Overview + +This library has been extracted (with some modifications) from +[`omniduct`](https://github.com/airbnb/omniduct), a library also principally +written by this author, where it was central to the extensible plugin +architecture. It places an emphasis on the functionality required to create a +well-documented extensible plugin system, whereby the act of subclassing is +sufficient to register the plugin and ensure compliance to the parent API. As +such, this library boasts the following features: + +- All subclasses of an interface must conform to the parent's API. +- Hierarchical runtime property existence and method signature checking. Methods + are permitted to add additional *optional* arguments, but otherwise must + conform to the API of their parent class (which themselves may have extended + the API of the interface). +- Subclass definition time hooks (e.g. for registration of subclasses into a + library of plugins, etc). +- Optional requirement for methods in subclasses to explicity decorate methods + with an `override` decorator when replacing methods on an interface, making + it clearer as to when a class is introducing new methods versus replacing + those that form the part of the interface API. +- Generation of clear docstrings on implementations that stitches together the + base interface documentation with any downstream extensions and quirks. +- Support for extracting the quirks documentation for a method from other method + docstrings, in the event that subclass implementations are done in an internal + method. +- Compatibility with ABCMeta from the standard library. + +## Example code + +```python +from abc import abstractmethod, abstractproperty +from interface_meta import InterfaceMeta, override, quirk_docs + +class MyInterface(metaclass=InterfaceMeta): + """ + An example interface. + """ + + INTERFACE_EXPLICIT_OVERRIDES = True + INTERFACE_RAISE_ON_VIOLATION = False + INTERFACE_SKIPPED_NAMES = {'__init__'} + + def __init__(self): + """ + MyInterface constructor. + """ + pass + + @abstractproperty + def name(self): + """ + The name of this interface. + """ + pass + + @quirk_docs(method='_do_stuff') + def do_stuff(self, a, b, c=1): + """ + Do things with the parameters. + """ + return self._do_stuff(a, b, c) + + @abstractmethod + def _do_stuff(self, a, b, c): + pass + +class MyImplementation(MyInterface): + """ + This implementation of the example interface works nicely. + """ + + @quirk_docs(method='_init', mro=False) + def __init__(self, a): + """ + MyImplementation constructor. + """ + self._init(a) + + def _init(self, a): + """ + In this instance, we do nothing with a. + """ + pass + + @property + @override + def name(self): + return "Peter" + + @override + def _do_stuff(self, a, b, c): + """ + In this implementation, we sum the parameters. + """ + return a + b + c +``` + +Running `help(MyImplementation)` reveals how the documentation is generated: + +```python +class MyImplementation(MyInterface) + | This implementation of the example interface works nicely. + | + | Method resolution order: + | MyImplementation + | MyInterface + | builtins.object + | + | Methods defined here: + | + | __init__(self, a) + | MyImplementation constructor. + | + | In this instance, we do nothing with a. + | + | do_stuff(self, a, b, c=1) + | Do things with the parameters. + | + | MyImplementation Quirks: + | In this implementation, we sum the parameters. + ... +``` + +## Related projects and prior art + +This library is released into an already crowded space, and the author would +like to recognise some of the already wonderful work done by others. The primary +difference between this and other libraries is typically these other libraries +focus more on abstracting interface definitions and compliance, and less on the +documentation and plugin registration work. While this work overlaps with these +projects, its approach is sufficiently different (in the author's opinion) +to warrant a separate library. + +- [`pure_interface`](https://github.com/seequent/pure_interface) +- [`python-interface`](https://github.com/ssanderson/interface) + +`python-interface` has an emphasis on ensuring that implementations of various +interfaces *strictly* adhere to the methods and properties associated with +the interface, and that helpful errors are raised when this is violated. + +By +comparison this library focusses on functional comformance to parent classes, +whereby methods on subclasses are allowed to include additional parameters. It +also focusses on ensuring that documentation for such quirks in method signatures are correctly composed into the final documentation rendered for that method. + + +%package help +Summary: Development documents and examples for interface-meta +Provides: python3-interface-meta-doc +%description help +# InterfaceMeta + +[](https://pypi.org/project/interface_meta/) + + +[](https://github.com/matthewwardrop/interface_meta/actions?query=workflow%3A%22Run+Tox+Tests%22) +[](https://codecov.io/gh/matthewwardrop/interface_meta) +[](https://github.com/psf/black) + +`interface_meta` provides a convenient way to expose an extensible API with +enforced method signatures and consistent documentation. + +- **Documentation:** See below (full documentation will come at some point). +- **Source:** https://github.com/matthewwardrop/interface_meta +- **Bug reports:** https://github.com/matthewwardrop/interface_meta/issues + +## Overview + +This library has been extracted (with some modifications) from +[`omniduct`](https://github.com/airbnb/omniduct), a library also principally +written by this author, where it was central to the extensible plugin +architecture. It places an emphasis on the functionality required to create a +well-documented extensible plugin system, whereby the act of subclassing is +sufficient to register the plugin and ensure compliance to the parent API. As +such, this library boasts the following features: + +- All subclasses of an interface must conform to the parent's API. +- Hierarchical runtime property existence and method signature checking. Methods + are permitted to add additional *optional* arguments, but otherwise must + conform to the API of their parent class (which themselves may have extended + the API of the interface). +- Subclass definition time hooks (e.g. for registration of subclasses into a + library of plugins, etc). +- Optional requirement for methods in subclasses to explicity decorate methods + with an `override` decorator when replacing methods on an interface, making + it clearer as to when a class is introducing new methods versus replacing + those that form the part of the interface API. +- Generation of clear docstrings on implementations that stitches together the + base interface documentation with any downstream extensions and quirks. +- Support for extracting the quirks documentation for a method from other method + docstrings, in the event that subclass implementations are done in an internal + method. +- Compatibility with ABCMeta from the standard library. + +## Example code + +```python +from abc import abstractmethod, abstractproperty +from interface_meta import InterfaceMeta, override, quirk_docs + +class MyInterface(metaclass=InterfaceMeta): + """ + An example interface. + """ + + INTERFACE_EXPLICIT_OVERRIDES = True + INTERFACE_RAISE_ON_VIOLATION = False + INTERFACE_SKIPPED_NAMES = {'__init__'} + + def __init__(self): + """ + MyInterface constructor. + """ + pass + + @abstractproperty + def name(self): + """ + The name of this interface. + """ + pass + + @quirk_docs(method='_do_stuff') + def do_stuff(self, a, b, c=1): + """ + Do things with the parameters. + """ + return self._do_stuff(a, b, c) + + @abstractmethod + def _do_stuff(self, a, b, c): + pass + +class MyImplementation(MyInterface): + """ + This implementation of the example interface works nicely. + """ + + @quirk_docs(method='_init', mro=False) + def __init__(self, a): + """ + MyImplementation constructor. + """ + self._init(a) + + def _init(self, a): + """ + In this instance, we do nothing with a. + """ + pass + + @property + @override + def name(self): + return "Peter" + + @override + def _do_stuff(self, a, b, c): + """ + In this implementation, we sum the parameters. + """ + return a + b + c +``` + +Running `help(MyImplementation)` reveals how the documentation is generated: + +```python +class MyImplementation(MyInterface) + | This implementation of the example interface works nicely. + | + | Method resolution order: + | MyImplementation + | MyInterface + | builtins.object + | + | Methods defined here: + | + | __init__(self, a) + | MyImplementation constructor. + | + | In this instance, we do nothing with a. + | + | do_stuff(self, a, b, c=1) + | Do things with the parameters. + | + | MyImplementation Quirks: + | In this implementation, we sum the parameters. + ... +``` + +## Related projects and prior art + +This library is released into an already crowded space, and the author would +like to recognise some of the already wonderful work done by others. The primary +difference between this and other libraries is typically these other libraries +focus more on abstracting interface definitions and compliance, and less on the +documentation and plugin registration work. While this work overlaps with these +projects, its approach is sufficiently different (in the author's opinion) +to warrant a separate library. + +- [`pure_interface`](https://github.com/seequent/pure_interface) +- [`python-interface`](https://github.com/ssanderson/interface) + +`python-interface` has an emphasis on ensuring that implementations of various +interfaces *strictly* adhere to the methods and properties associated with +the interface, and that helpful errors are raised when this is violated. + +By +comparison this library focusses on functional comformance to parent classes, +whereby methods on subclasses are allowed to include additional parameters. It +also focusses on ensuring that documentation for such quirks in method signatures are correctly composed into the final documentation rendered for that method. + + +%prep +%autosetup -n interface-meta-1.3.0 + +%build +%py3_build + +%install +%py3_install +install -d -m755 %{buildroot}/%{_pkgdocdir} +if [ -d doc ]; then cp -arf doc %{buildroot}/%{_pkgdocdir}; fi +if [ -d docs ]; then cp -arf docs %{buildroot}/%{_pkgdocdir}; fi +if [ -d example ]; then cp -arf example %{buildroot}/%{_pkgdocdir}; fi +if [ -d examples ]; then cp -arf examples %{buildroot}/%{_pkgdocdir}; fi +pushd %{buildroot} +if [ -d usr/lib ]; then + find usr/lib -type f -printf "/%h/%f\n" >> filelist.lst +fi +if [ -d usr/lib64 ]; then + find usr/lib64 -type f -printf "/%h/%f\n" >> filelist.lst +fi +if [ -d usr/bin ]; then + find usr/bin -type f -printf "/%h/%f\n" >> filelist.lst +fi +if [ -d usr/sbin ]; then + find usr/sbin -type f -printf "/%h/%f\n" >> filelist.lst +fi +touch doclist.lst +if [ -d usr/share/man ]; then + find usr/share/man -type f -printf "/%h/%f.gz\n" >> doclist.lst +fi +popd +mv %{buildroot}/filelist.lst . +mv %{buildroot}/doclist.lst . + +%files -n python3-interface-meta -f filelist.lst +%dir %{python3_sitelib}/* + +%files help -f doclist.lst +%{_docdir}/* + +%changelog +* Mon Apr 10 2023 Python_Bot <Python_Bot@openeuler.org> - 1.3.0-1 +- Package Spec generated |