Advanced descriptors for special cases.
Project description
Advanced descriptors
====================
.. image:: https://travis-ci.com/python-useful-helpers/advanced-descriptors.svg?branch=master
:target: https://travis-ci.com/python-useful-helpers/advanced-descriptors
.. image:: https://dev.azure.com/python-useful-helpers/advanced-descriptors/_apis/build/status/python-useful-helpers.advanced-descriptors?branchName=master
:alt: Azure DevOps builds
:target: https://dev.azure.com/python-useful-helpers/advanced-descriptors/_build?definitionId=2
.. image:: https://coveralls.io/repos/github/python-useful-helpers/advanced-descriptors/badge.svg?branch=master
:target: https://coveralls.io/github/python-useful-helpers/advanced-descriptors?branch=master
.. image:: https://readthedocs.org/projects/advanced-descriptors/badge/?version=latest
:target: http://advanced-descriptors.readthedocs.io/
:alt: Documentation Status
.. image:: https://img.shields.io/pypi/v/advanced-descriptors.svg
:target: https://pypi.python.org/pypi/advanced-descriptors
.. image:: https://img.shields.io/pypi/pyversions/advanced-descriptors.svg
:target: https://pypi.python.org/pypi/advanced-descriptors
.. image:: https://img.shields.io/pypi/status/advanced-descriptors.svg
:target: https://pypi.python.org/pypi/advanced-descriptors
.. image:: https://img.shields.io/github/license/python-useful-helpers/advanced-descriptors.svg
:target: https://raw.githubusercontent.com/python-useful-helpers/advanced-descriptors/master/LICENSE
.. image:: https://img.shields.io/badge/code%20style-black-000000.svg
:target: https://github.com/ambv/black
This package includes helpers for special cases:
* `SeparateClassMethod` - allow to have classmethod and normal method both with the same name.
* `AdvancedProperty` - property with possibility to set class wide getter.
* `LogOnAccess` - property with logging on successful get/set/delete or failure.
SeparateClassMethod
-------------------
This descriptor can be set using standard decorator syntax.
Create instance with arguments:
.. code-block:: python
def imeth(instance):
return instance.value
def cmeth(owner):
return owner.value
class Target(object):
value = 1
def __init__(self):
self.value = 2
getval = advanced_descriptors.SeparateClassMethod(
imeth, cmeth
)
Create instance wrapping as decorator:
.. code-block:: python
class Target(object):
value = 1
def __init__(self):
self.value = 2
@advanced_descriptors.SeparateClassMethod
def getval(self):
return self.value
@getval.class_method
def getval(cls):
return cls.value
Cases with method only and classmethod only is useless:
method as-is and `@classmethod` should be used in corresponding cases.
.. note::
classmethod receives class as argument. IDE's don't know about custom descriptors and substitutes `self` by default.
AdvancedProperty
----------------
This descriptor should be used in cases, when in addition to normal property API, class getter is required.
If class-wide setter and deleter also required - you should use standard propery in metaclass.
Usage examples:
1. In addition to normal property API:
.. code-block:: python
class Target(object):
_value = 777
def __init__(self):
self._value = 42
@advanced_descriptors.AdvancedProperty
def val(self):
return self._value
@val.setter
def val(self, value):
self._value = value
@val.deleter
def val(self):
self._value = 0
@val.cgetter
def val(cls):
return cls._value
2. Use class-wide getter for instance too:
.. code-block:: python
class Target(object):
_value = 1
val = advanced_descriptors.AdvancedProperty()
@val.cgetter
def val(cls):
return cls._value
.. note::
class-wide getter receives class as argument. IDE's don't know about custom descriptors and substitutes `self` by default.
LogOnAccess
-----------
This special case of property is useful in cases, where a lot of properties should be logged by similar way without writing a lot of code.
Basic API is conform with `property`, but in addition it is possible to customize logger, log levels and log conditions.
Usage examples:
1. Simple usage. All by default, logger is re-used from instance if available with names `logger` or `log` else used internal `advanced_descriptors.log_on_access` logger:
.. code-block:: python
import logging
class Target(object):
def init(self, val='ok')
self.val = val
self.logger = logging.get_logger(self.__class__.__name__) # Single for class, follow subclassing
def __repr__(self):
return "{cls}(val={self.val})".format(cls=self.__class__.__name__, self=self)
@advanced_descriptors.LogOnAccess
def ok(self):
return self.val
@ok.setter
def ok(self, val):
self.val = val
@ok.deleter
def ok(self):
self.val = ""
2. Use with global logger for class:
.. code-block:: python
class Target(object):
def init(self, val='ok')
self.val = val
def __repr__(self):
return "{cls}(val={self.val})".format(cls=self.__class__.__name__, self=self)
@advanced_descriptors.LogOnAccess
def ok(self):
return self.val
@ok.setter
def ok(self, val):
self.val = val
@ok.deleter
def ok(self):
self.val = ""
ok.logger = 'test_logger'
ok.log_level = logging.INFO
ok.exc_level = logging.ERROR
ok.log_object_repr = True # As by default
ok.log_success = True # As by default
ok.log_failure = True # As by default
ok.log_traceback = True # As by default
ok.override_name = None # As by default: use original name
Testing
=======
The main test mechanism for the package `advanced-descriptors` is using `tox`.
Available environments can be collected via `tox -l`
CI systems
==========
For code checking several CI systems is used in parallel:
1. `Travis CI: <https://travis-ci.com/python-useful-helpers/advanced-descriptors>`_ is used for checking: PEP8, pylint, bandit, installation possibility and unit tests. Also it's publishes coverage on coveralls.
2. `coveralls: <https://coveralls.io/github/python-useful-helpers/advanced-descriptors>`_ is used for coverage display.
3. `Azure CI: <https://dev.azure.com/python-useful-helpers/advanced-descriptors/_build?definitionId=2>`_ is used for functional tests on Windows.
CD system
=========
`Travis CI: <https://travis-ci.org/python-useful-helpers/advanced-descriptors>`_ is used for package delivery on PyPI.
====================
.. image:: https://travis-ci.com/python-useful-helpers/advanced-descriptors.svg?branch=master
:target: https://travis-ci.com/python-useful-helpers/advanced-descriptors
.. image:: https://dev.azure.com/python-useful-helpers/advanced-descriptors/_apis/build/status/python-useful-helpers.advanced-descriptors?branchName=master
:alt: Azure DevOps builds
:target: https://dev.azure.com/python-useful-helpers/advanced-descriptors/_build?definitionId=2
.. image:: https://coveralls.io/repos/github/python-useful-helpers/advanced-descriptors/badge.svg?branch=master
:target: https://coveralls.io/github/python-useful-helpers/advanced-descriptors?branch=master
.. image:: https://readthedocs.org/projects/advanced-descriptors/badge/?version=latest
:target: http://advanced-descriptors.readthedocs.io/
:alt: Documentation Status
.. image:: https://img.shields.io/pypi/v/advanced-descriptors.svg
:target: https://pypi.python.org/pypi/advanced-descriptors
.. image:: https://img.shields.io/pypi/pyversions/advanced-descriptors.svg
:target: https://pypi.python.org/pypi/advanced-descriptors
.. image:: https://img.shields.io/pypi/status/advanced-descriptors.svg
:target: https://pypi.python.org/pypi/advanced-descriptors
.. image:: https://img.shields.io/github/license/python-useful-helpers/advanced-descriptors.svg
:target: https://raw.githubusercontent.com/python-useful-helpers/advanced-descriptors/master/LICENSE
.. image:: https://img.shields.io/badge/code%20style-black-000000.svg
:target: https://github.com/ambv/black
This package includes helpers for special cases:
* `SeparateClassMethod` - allow to have classmethod and normal method both with the same name.
* `AdvancedProperty` - property with possibility to set class wide getter.
* `LogOnAccess` - property with logging on successful get/set/delete or failure.
SeparateClassMethod
-------------------
This descriptor can be set using standard decorator syntax.
Create instance with arguments:
.. code-block:: python
def imeth(instance):
return instance.value
def cmeth(owner):
return owner.value
class Target(object):
value = 1
def __init__(self):
self.value = 2
getval = advanced_descriptors.SeparateClassMethod(
imeth, cmeth
)
Create instance wrapping as decorator:
.. code-block:: python
class Target(object):
value = 1
def __init__(self):
self.value = 2
@advanced_descriptors.SeparateClassMethod
def getval(self):
return self.value
@getval.class_method
def getval(cls):
return cls.value
Cases with method only and classmethod only is useless:
method as-is and `@classmethod` should be used in corresponding cases.
.. note::
classmethod receives class as argument. IDE's don't know about custom descriptors and substitutes `self` by default.
AdvancedProperty
----------------
This descriptor should be used in cases, when in addition to normal property API, class getter is required.
If class-wide setter and deleter also required - you should use standard propery in metaclass.
Usage examples:
1. In addition to normal property API:
.. code-block:: python
class Target(object):
_value = 777
def __init__(self):
self._value = 42
@advanced_descriptors.AdvancedProperty
def val(self):
return self._value
@val.setter
def val(self, value):
self._value = value
@val.deleter
def val(self):
self._value = 0
@val.cgetter
def val(cls):
return cls._value
2. Use class-wide getter for instance too:
.. code-block:: python
class Target(object):
_value = 1
val = advanced_descriptors.AdvancedProperty()
@val.cgetter
def val(cls):
return cls._value
.. note::
class-wide getter receives class as argument. IDE's don't know about custom descriptors and substitutes `self` by default.
LogOnAccess
-----------
This special case of property is useful in cases, where a lot of properties should be logged by similar way without writing a lot of code.
Basic API is conform with `property`, but in addition it is possible to customize logger, log levels and log conditions.
Usage examples:
1. Simple usage. All by default, logger is re-used from instance if available with names `logger` or `log` else used internal `advanced_descriptors.log_on_access` logger:
.. code-block:: python
import logging
class Target(object):
def init(self, val='ok')
self.val = val
self.logger = logging.get_logger(self.__class__.__name__) # Single for class, follow subclassing
def __repr__(self):
return "{cls}(val={self.val})".format(cls=self.__class__.__name__, self=self)
@advanced_descriptors.LogOnAccess
def ok(self):
return self.val
@ok.setter
def ok(self, val):
self.val = val
@ok.deleter
def ok(self):
self.val = ""
2. Use with global logger for class:
.. code-block:: python
class Target(object):
def init(self, val='ok')
self.val = val
def __repr__(self):
return "{cls}(val={self.val})".format(cls=self.__class__.__name__, self=self)
@advanced_descriptors.LogOnAccess
def ok(self):
return self.val
@ok.setter
def ok(self, val):
self.val = val
@ok.deleter
def ok(self):
self.val = ""
ok.logger = 'test_logger'
ok.log_level = logging.INFO
ok.exc_level = logging.ERROR
ok.log_object_repr = True # As by default
ok.log_success = True # As by default
ok.log_failure = True # As by default
ok.log_traceback = True # As by default
ok.override_name = None # As by default: use original name
Testing
=======
The main test mechanism for the package `advanced-descriptors` is using `tox`.
Available environments can be collected via `tox -l`
CI systems
==========
For code checking several CI systems is used in parallel:
1. `Travis CI: <https://travis-ci.com/python-useful-helpers/advanced-descriptors>`_ is used for checking: PEP8, pylint, bandit, installation possibility and unit tests. Also it's publishes coverage on coveralls.
2. `coveralls: <https://coveralls.io/github/python-useful-helpers/advanced-descriptors>`_ is used for coverage display.
3. `Azure CI: <https://dev.azure.com/python-useful-helpers/advanced-descriptors/_build?definitionId=2>`_ is used for functional tests on Windows.
CD system
=========
`Travis CI: <https://travis-ci.org/python-useful-helpers/advanced-descriptors>`_ is used for package delivery on PyPI.
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
Advanced-Descriptors-3.0.2.tar.gz
(37.8 kB
view hashes)
Built Distributions
Close
Hashes for Advanced-Descriptors-3.0.2.tar.gz
Algorithm | Hash digest | |
---|---|---|
SHA256 | 873bf253f848cfd8208247318ac3b8f0e8e14c2907a7161425dfffa6cddb5aaa |
|
MD5 | 5bd690eaa790ec1a37c56d1687446038 |
|
BLAKE2b-256 | 64830452c6d0c9ca3734b9c88608798e15365ce3b2c2cdbf5f5fbda02dfc1e13 |
Close
Hashes for Advanced_Descriptors-3.0.2-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | a88f7d1d97d03fcdff1269b6e02175d29cc4dd496f5058cbd881d89d6895fd14 |
|
MD5 | aec519a0b18bd31b2e0c3bd97073b4b0 |
|
BLAKE2b-256 | 800a4a287bc42e8c50258e1a045d496d41e64c84ae466e5bc77ba2df10521f9c |
Close
Hashes for Advanced_Descriptors-3.0.2-cp37-cp37m-win_amd64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 7d62f23ae3b28521f79ec5cb1b129ab7ddd1b308384b497008acd76f71401197 |
|
MD5 | 74a586bd3a6081012e8748b5b730b0bf |
|
BLAKE2b-256 | e8db7af9b3714c14db986ee35ab205c58569093ead1b0e667ee7e587533e47dc |
Close
Hashes for Advanced_Descriptors-3.0.2-cp37-cp37m-win32.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 6ea5de4e657bc506d89c28f1b282fc97591ee4c7b2803fb5c3970d798fd4a5d6 |
|
MD5 | 21cb3b40479f30cc59f3a6563e5dc57d |
|
BLAKE2b-256 | 9bd71cb720ae4b381e3c90a9b41b0c6b1c6cda576c1f2ae7d1b60822bdb75a0f |
Close
Hashes for Advanced_Descriptors-3.0.2-cp37-cp37m-manylinux1_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 4cdb303d9f1566d05ad2e383f38822e81af27e4e8f8824f3fe3e4b2f65d9633c |
|
MD5 | b0e2ec591374da02ef6d7e1fa184a0c3 |
|
BLAKE2b-256 | 240088deededfaf1dc7c1c40f71ab9a822664d6639dbd782568818900afb6d9e |
Close
Hashes for Advanced_Descriptors-3.0.2-cp37-cp37m-manylinux1_i686.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 7d2e8845b6debcaf73ce8ade73081dcfc2e3e2b95c73eb99453720101e26623f |
|
MD5 | 6006f39d5568d8b9b7193c74ad7761c2 |
|
BLAKE2b-256 | b4db3cd61695382a398800c52c96132d80068e1e6ebe1fbc38a17585c3c01c57 |
Close
Hashes for Advanced_Descriptors-3.0.2-cp36-cp36m-win_amd64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 7c9801fc7ac11ffa938bc6a0e2488c1f4f9355db73f1cd07820432f88837d5fc |
|
MD5 | 8a91a9eeed348123d46433b763595871 |
|
BLAKE2b-256 | 9341ca7c191d32fc6e779a29d60d21fceffca7b680a3a8380104120f796f73b0 |
Close
Hashes for Advanced_Descriptors-3.0.2-cp36-cp36m-win32.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | edc548d03230b2f01753f2a5f595c1d5cda795cb2f3ce8f9832db6c477ced863 |
|
MD5 | 080143b6b2e5675876cdf5005ddf11d3 |
|
BLAKE2b-256 | f4812d51311b1fe44f65096105cf32e69063afe70276644b9183caa7e067b8cd |
Close
Hashes for Advanced_Descriptors-3.0.2-cp36-cp36m-manylinux1_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 740e1179dac661413c8b2452450ba2c889d19d8521038a320f0c2e058e9210e1 |
|
MD5 | 776b4d1689fefe0d08393bbf19edd782 |
|
BLAKE2b-256 | 36a9a6d30438705fcf86c55ddb5057b3a25fbedef4c5934dc433656fc4d3c9df |
Close
Hashes for Advanced_Descriptors-3.0.2-cp36-cp36m-manylinux1_i686.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 5bc0c73eefca7d965711dfcc653db2161e020b734f0a5562050a16ad6b35d65a |
|
MD5 | 10dd1858cc1963f2375adf94c57eb433 |
|
BLAKE2b-256 | a1e7dd75781fcf1497f05bdc1ac7e183653166eb3922dd3ee16a0f5a1726f907 |