This package provides a support to simplify the use of annotations in
Zope.
.. contents::
Setting up ``grokcore.annotation``
==================================
This package is essentially set up like the `grokcore.component`_
package, please refer to its documentation for details. The only
additional ZCML line you will need is::
<include package="grokcore.annotation" />
Put this somewhere near the top of your root ZCML file but below the
line where you include ``grokcore.component``'s configuration.
Example
=======
Here a simple example of use of an annotation::
import grokcore.annotation
from zope import interface
# Create a model and an interface you want to adapt it to
# and an annotation class to implement the persistent adapter.
class Mammoth(grokcore.annotation.Model):
pass
class ISerialBrand(interface.Interface):
unique = interface.Attribute("Brands")
class Branding(grokcore.annotation.Annotation):
grokcore.annotation.implements(ISerialBrand)
unique = 0
# Grok the above code, then create some mammoths
manfred = Mammoth()
mumbles = Mammoth()
# creating Annotations work just like Adapters
livestock1 = ISerialBrand(manfred)
livestock2 = ISerialBrand(mumbles)
# except you can store data in them, this data will transparently persist
# in the database for as long as the object exists
livestock1.unique = 101
livestock2.unique = 102
# attributes not listed in the interface will also be persisted
# on the annotation
livestock2.foo = "something"
API Overview
============
Base classes
------------
``Annotation``
Base class for an Annotation. Inherits from the
persistent.Persistent class.
``Model``
Base class for a Model on which you want to use an annotation.
``queryAnnotation(model, interface)``
Query the annotation on the given model for the given
interface. Return the annotation if found, None otherwise. This
will not *make* any write operation.
``deleteAnnotation(model, interface)``
Look for the given annotation and delete it from the model.
``LazyAnnotation``
Base class for an annotation. It only writes a database object when
explicitly setting values on the lazy properties.
``LazyAnnotationProperty``
Property implementation that works with ``LazyAnnotation``.
In addition, the ``grokcore.annotation`` package exposes the
`grokcore.component`_ API.
.. _grokcore.component: http://pypi.python.org/pypi/grokcore.component
Changes
=======
4.0 (2023-07-12)
----------------
- Add support for Python 3.10, 3.11.
- Drop support for Python 2.7, 3.5, 3.6.
- Drop support for deprecated ``python setup.py test``.
3.2 (2021-08-31)
----------------
- ``grokcore.annotation.testing.warn`` was removed as it was not used
internally. If you still need it, a copy is in ``grokcore.view.testing``.
- Add ``_p_changed`` property to the LazyAnnotation object, proxying it to
the actual Storage object. That way the "API" for explicitely marking
objects as changed is the same regaredless of a "normal" annotation object
or an lazy annotation object.
- Add support for Python 3.7, 3.8 and 3.9.
- Drop support for Python 3.4.
3.1 (2020-10-27)
----------------
- Add support for `FieldUpdatedEvent` in `LazyPropertyAnnotation` to
mirror the behavior of zope.schema.
3.0.1 (2018-01-17)
------------------
- Replace the use of `grok.implements()` with the `@grok.implementer()`
directive throughout.
3.0.0 (2018-01-12)
------------------
- Rearrange tests such that Travis CI can pick up all functional tests too.
1.6 (2017-05-30)
----------------
- Add LazyAnnotation and LazyAnnotationProperty.
- Drop support of Python 2.6 and claim support for Python 3.4, 3.5, 3.6 and PyPy.
1.5.1 (2016-01-29)
------------------
- Update tests.
1.5 (2014-10-20)
----------------
- Updating MANIFEST.in, fixing a brown paper bag release.
1.4 (2014-10-17)
----------------
- Add ``queryAnnotation()`` to return an annotation. Return None if it
doesn't exists. This helper will never do any write operation in the
database.
- Add ``deleteAnnotation()`` to delete an annotation (if it exists).
1.3 (2012-05-01)
----------------
- Use ``provideAdapter()`` from grokcore.component.util.
- Made package comply to zope.org repository policy.
1.2 (2009-12-13)
----------------
* Use zope.container instead of zope.app.container.
1.1 (2009-09-18)
----------------
* The annotation object become really a contained object to be aware
of its context, and name.
* Use 1.0b1 versions.cfg in Grok's release info instead of a local
copy; a local copy for all grokcore packages is just too hard to
maintain.
1.0.1 (2009-06-30)
------------------
* Reupload to pypi with a correct version of Python which doesn't
have a distutils bug.
1.0 (2009-06-29)
----------------
* Created ``grokcore.Annotation`` by factoring annotation components,
grokkers and directives out of Grok.
Raw data
{
"_id": null,
"home_page": "https://github.com/zopefoundation/grokcore.annotation",
"name": "grokcore.annotation",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "",
"keywords": "",
"author": "Grok Team",
"author_email": "zope-dev@zope.dev",
"download_url": "https://files.pythonhosted.org/packages/b6/f8/aa70602d0942ff4982a17eaeb14eccdbcb198c8ab4a73661c5efee0b16e8/grokcore.annotation-4.0.tar.gz",
"platform": null,
"description": "This package provides a support to simplify the use of annotations in\nZope.\n\n.. contents::\n\nSetting up ``grokcore.annotation``\n==================================\n\nThis package is essentially set up like the `grokcore.component`_\npackage, please refer to its documentation for details. The only\nadditional ZCML line you will need is::\n\n <include package=\"grokcore.annotation\" />\n\nPut this somewhere near the top of your root ZCML file but below the\nline where you include ``grokcore.component``'s configuration.\n\nExample\n=======\n\nHere a simple example of use of an annotation::\n\n import grokcore.annotation\n from zope import interface\n\n # Create a model and an interface you want to adapt it to\n # and an annotation class to implement the persistent adapter.\n class Mammoth(grokcore.annotation.Model):\n pass\n\n class ISerialBrand(interface.Interface):\n unique = interface.Attribute(\"Brands\")\n\n class Branding(grokcore.annotation.Annotation):\n grokcore.annotation.implements(ISerialBrand)\n unique = 0\n\n # Grok the above code, then create some mammoths\n manfred = Mammoth()\n mumbles = Mammoth()\n\n # creating Annotations work just like Adapters\n livestock1 = ISerialBrand(manfred)\n livestock2 = ISerialBrand(mumbles)\n\n # except you can store data in them, this data will transparently persist\n # in the database for as long as the object exists\n livestock1.unique = 101\n livestock2.unique = 102\n\n # attributes not listed in the interface will also be persisted\n # on the annotation\n livestock2.foo = \"something\"\n\nAPI Overview\n============\n\nBase classes\n------------\n\n``Annotation``\n Base class for an Annotation. Inherits from the\n persistent.Persistent class.\n\n``Model``\n Base class for a Model on which you want to use an annotation.\n\n``queryAnnotation(model, interface)``\n Query the annotation on the given model for the given\n interface. Return the annotation if found, None otherwise. This\n will not *make* any write operation.\n\n``deleteAnnotation(model, interface)``\n Look for the given annotation and delete it from the model.\n\n``LazyAnnotation``\n Base class for an annotation. It only writes a database object when\n explicitly setting values on the lazy properties.\n\n``LazyAnnotationProperty``\n Property implementation that works with ``LazyAnnotation``.\n\nIn addition, the ``grokcore.annotation`` package exposes the\n`grokcore.component`_ API.\n\n.. _grokcore.component: http://pypi.python.org/pypi/grokcore.component\n\nChanges\n=======\n\n4.0 (2023-07-12)\n----------------\n\n- Add support for Python 3.10, 3.11.\n\n- Drop support for Python 2.7, 3.5, 3.6.\n\n- Drop support for deprecated ``python setup.py test``.\n\n\n3.2 (2021-08-31)\n----------------\n\n- ``grokcore.annotation.testing.warn`` was removed as it was not used\n internally. If you still need it, a copy is in ``grokcore.view.testing``.\n\n- Add ``_p_changed`` property to the LazyAnnotation object, proxying it to\n the actual Storage object. That way the \"API\" for explicitely marking\n objects as changed is the same regaredless of a \"normal\" annotation object\n or an lazy annotation object.\n\n- Add support for Python 3.7, 3.8 and 3.9.\n\n- Drop support for Python 3.4.\n\n\n3.1 (2020-10-27)\n----------------\n\n- Add support for `FieldUpdatedEvent` in `LazyPropertyAnnotation` to\n mirror the behavior of zope.schema.\n\n\n3.0.1 (2018-01-17)\n------------------\n\n- Replace the use of `grok.implements()` with the `@grok.implementer()`\n directive throughout.\n\n3.0.0 (2018-01-12)\n------------------\n\n- Rearrange tests such that Travis CI can pick up all functional tests too.\n\n1.6 (2017-05-30)\n----------------\n\n- Add LazyAnnotation and LazyAnnotationProperty.\n\n- Drop support of Python 2.6 and claim support for Python 3.4, 3.5, 3.6 and PyPy.\n\n1.5.1 (2016-01-29)\n------------------\n\n- Update tests.\n\n1.5 (2014-10-20)\n----------------\n\n- Updating MANIFEST.in, fixing a brown paper bag release.\n\n1.4 (2014-10-17)\n----------------\n\n- Add ``queryAnnotation()`` to return an annotation. Return None if it\n doesn't exists. This helper will never do any write operation in the\n database.\n\n- Add ``deleteAnnotation()`` to delete an annotation (if it exists).\n\n1.3 (2012-05-01)\n----------------\n\n- Use ``provideAdapter()`` from grokcore.component.util.\n\n- Made package comply to zope.org repository policy.\n\n1.2 (2009-12-13)\n----------------\n\n* Use zope.container instead of zope.app.container.\n\n1.1 (2009-09-18)\n----------------\n\n* The annotation object become really a contained object to be aware\n of its context, and name.\n\n* Use 1.0b1 versions.cfg in Grok's release info instead of a local\n copy; a local copy for all grokcore packages is just too hard to\n maintain.\n\n1.0.1 (2009-06-30)\n------------------\n\n* Reupload to pypi with a correct version of Python which doesn't\n have a distutils bug.\n\n1.0 (2009-06-29)\n----------------\n\n* Created ``grokcore.Annotation`` by factoring annotation components,\n grokkers and directives out of Grok.\n",
"bugtrack_url": null,
"license": "ZPL 2.1",
"summary": "Grok-like configuration for Zope annotations",
"version": "4.0",
"project_urls": {
"Homepage": "https://github.com/zopefoundation/grokcore.annotation"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "cc8b793f90119b8f1dec8a870b51ec97a5657753909641a0fdd133af2f0217e1",
"md5": "e47db2528901485d59408f4e39f3cc31",
"sha256": "c0a1b79a3fa600ad19d84d25b299b57d2a80cc558b9992335c10fe5c668b4183"
},
"downloads": -1,
"filename": "grokcore.annotation-4.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e47db2528901485d59408f4e39f3cc31",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 18606,
"upload_time": "2023-07-12T06:41:18",
"upload_time_iso_8601": "2023-07-12T06:41:18.942552Z",
"url": "https://files.pythonhosted.org/packages/cc/8b/793f90119b8f1dec8a870b51ec97a5657753909641a0fdd133af2f0217e1/grokcore.annotation-4.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "b6f8aa70602d0942ff4982a17eaeb14eccdbcb198c8ab4a73661c5efee0b16e8",
"md5": "01359da488576b5c5668589a0f502f82",
"sha256": "049241648745ddef49b6a11d74ac59b8fcd1ca77e65100e527d153598c91c216"
},
"downloads": -1,
"filename": "grokcore.annotation-4.0.tar.gz",
"has_sig": false,
"md5_digest": "01359da488576b5c5668589a0f502f82",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 15112,
"upload_time": "2023-07-12T06:41:21",
"upload_time_iso_8601": "2023-07-12T06:41:21.235930Z",
"url": "https://files.pythonhosted.org/packages/b6/f8/aa70602d0942ff4982a17eaeb14eccdbcb198c8ab4a73661c5efee0b16e8/grokcore.annotation-4.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-07-12 06:41:21",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "zopefoundation",
"github_project": "grokcore.annotation",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "grokcore.annotation"
}
JSON
