Metadata-Version: 2.0
Name: Advanced-Descriptors
Version: 0.5.0
Summary: Advanded descriptors for special cases.
Home-page: https://github.com/penguinolog/advanced-descriptors
Author: Alexey Stepanov
Author-email: penguinolog@gmail.com
License: Apache License, Version 2.0
Description-Content-Type: UNKNOWN
Keywords: descriptor,property,classmethod,development
Platform: UNKNOWN
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.4
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Requires-Python: >=2.6,!=3.0.*,!=3.1.*,!=3.2.*,!=3.3.*
Requires-Dist: typing (>=3.6); python_version >= "2.7"

Advanced descriptors
====================

.. image:: https://travis-ci.org/penguinolog/advanced-descriptors.svg?branch=master
    :target: https://travis-ci.org/penguinolog/advanced-descriptors
.. image:: https://coveralls.io/repos/github/penguinolog/advanced-descriptors/badge.svg?branch=master
    :target: https://coveralls.io/github/penguinolog/advanced-descriptors?branch=master
.. image:: https://img.shields.io/github/license/penguinolog/advanced-descriptors.svg
    :target: https://raw.githubusercontent.com/penguinolog/advanced-descriptors/master/LICENSE

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.

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:

    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.

Testing
=======
The main test mechanism for the package `advanced-descriptors` is using `tox`.
Test environments available:

::

    pep8
    py27
    py34
    py35
    py36
    pypy
    pypy3
    pylint
    pep257

CI systems
==========
For code checking several CI systems is used in parallel:

1. `Travis CI: <https://travis-ci.org/penguinolog/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/penguinolog/advanced-descriptors>`_ is used for coverage display.


