This package provides basic elements for defining Zope permissions and
security checkers without ZCML.
.. contents::
Setting up ``grokcore.security``
================================
This package is essentially set up like the `grokcore.component`_
package, please refer to its documentation for details. The
additional ZCML lines you will need are::
<include package="grokcore.security" file="meta.zcml" />
<include package="grokcore.security" />
Put this somewhere near the top of your root ZCML file but below the
line where you include ``grokcore.component``'s configuration.
Defining permissions
====================
In `grokcore.component`_, various components are defined (and
automatically registered) by subclassing from certain baseclasses.
The same applies to defining permissions with ``grokcore.security`` as
well::
import grokcore.security
class EditContent(grokcore.security.Permission):
grokcore.security.name('mypkg.EditContent')
This defines a permission with the ID ``mypkg.EditContent``. You must
always specify this ID explicitly. In addition, you can also give the
permission a human-readable title and description. This is useful
when your application provides lists of permissions somewhere and you
don't want to bother users with deciphering the dotted IDs::
import grokcore.security
class EditContent(grokcore.security.Permission):
grokcore.security.name('mypkg.EditContent')
grokcore.security.title('Edit content')
grokcore.security.description('Anyone who has this permission may '
'modify content in the application.')
Defining checkers for components
================================
``grokcore.security`` provides some means for defining checkers for
components:
* ``grokcore.security.require(permission)`` which can be used either
as a class-level directive to set a permission for a whole
component, or as a decorator to set a permission for a function or
method.
* ``protect_getattr`` and ``protect_setattr``, available from
``grokcore.security.util``, which take a class, an attribute name
and a permission as arguments and define Zope security checkers for
getting or setting a particular attribute on instance of said class.
With these, you can build grokkers for components that need security
declarations. For instance, the `grokcore.view`_ package uses them to
define a grokker that makes security declarations for views::
class ViewSecurityGrokker(martian.ClassGrokker):
martian.component(grokcore.view.View)
martian.directive(grokcore.security.require, name='permission')
def execute(self, factory, config, permission, **kw):
for method_name in zope.publisher.interfaces.browser.IBrowserPage:
config.action(
discriminator=('protectName', factory, method_name),
callable=grokcore.security.util.protect_getattr,
args=(factory, method_name, permission),
)
return True
With such a grokker, it is possible to protect views like so::
class Edit(grokcore.view.View):
grokcore.security.require(EditContent)
Note how we can simply pass a permission class to the ``require``
directive. Alternatively, you can pass the permission ID::
class Edit(grokcore.view.View):
grokcore.security.require('mypkg.EditContent')
If you wanted to be able to define permissions for individual class
methods rather than the whole class, you would simply base your
grokker on ``martian.MethodGrokker`` rather than ``ClassGrokker``.
The actual mechanics of defining a checker are the same.
Please note that ``grokcore.security`` does not yet provide directives
that allow you to specify permissions for simple attribute access
(read and write).
API overview
============
``Permission``
Base class for defining permissions. Use the ``name`` directive
to define the mandatory permission ID. Optionally use the
``title`` and ``description`` directives to give the permission
human-readable information.
``Public``
Special permission that can be referred to whenever a component
should not be protected by a permission at all (public access).
``require(permission_class_or_id)``
declares that the use of a particular component (when used as a
class-level directive) or a method (when used as a method
decorator) requires a certain permission. The argument can either
be a permission class (subclass of ``Permission``) or a permission
ID.
In addition, the ``grokcore.security`` package exposes the
`grokcore.component`_ API.
.. _grokcore.component: http://pypi.python.org/pypi/grokcore.component
.. _grokcore.view: http://pypi.python.org/pypi/grokcore.view
Changes
=======
4.0 (2023-07-11)
----------------
- Add support for Python 3.7, 3.8, 3.9, 3.10, 3.11.
- Drop support for Python 2.7, 3.4, 3.5, 3.6.
3.0.1 (2018-01-12)
------------------
- Rearrange tests such that Travis CI can pick up all functional tests too.
3.0.0 (2018-01-05)
------------------
- Fix several test error that came to light.
1.7 (2018-01-03)
----------------
- Python 3 compatibility.
1.6.3 (2016-01-29)
------------------
- Update tests.
1.6.2 (2012-05-07)
------------------
- Properly declare zope.dottedname as a dependency.
1.6.1 (2012-05-02)
------------------
- Fix the package to properly work if the extra ``role`` is not
specified.
1.6 (2012-05-01)
----------------
- The Permission and Role components moved from the grok package to the
grokcore.security package where it belongs.
- The permissions() directive moved from the grok package to
grokcore.security where it belongs.
1.5 (2010-11-01)
----------------
- Upped the requirements for martian and grokcore.component.
- Made package comply to zope.org repository policy.
1.4 (2009-12-13)
----------------
* **note** Backed out the version requirements for
grokcore.component-2.0 and martian-0.12. These requirements
stood in the way of further development especially towards
grok-1.1 based on the ZTK. The 1.3 version should probably
have been called 2.0 like with grokcore.component.
* Ported setup.py dependency fixes from trunk.
* Use zope.security instead of zope.app.security.
1.3 (2009-09-16)
----------------
* Use the grok.zope.org/releaseinfo information instead of our own
copy of ``versions.cfg``, for easier maintenance.
* Depend on grokcore.component 2.0 and the 0.12 Martian - this changes
inheritance issues but doesn't appear to affect grokcore.security
itself.
1.2 (2009-09-14)
----------------
* Changed the default permissions from grok.View to zope.View. There seems no
particular reason not to use the standard zope.View permission defined
in zope.app.security.
NOTE: YOU MUST STILL ASSIGN THIS PERMISSION TO USERS IN YOUR
site.zcml FILE. OTHERWISE YOU DO NOT HAVE ACCESS TO ANY VIEWS.
* Made sure to include zope.app.security configuration as well, as that
package defines the zope.View permission. Note that in the future this will
change to zope.security.
* Bring versions.cfg in line with grok 1.0 release candidate
versions.cfg.
1.1 (2009-07-03)
----------------
* Changed the default permissions from zope.Public to grok.View.
NOTE: YOU MUST ASSIGN THIS PERMISSION TO USERS IN YOUR
site.zcml FILE. OTHERWISE YOU DO NOT HAVE ACCESS TO ANY VIEWS.
1.0 (2008-08-03)
----------------
* Created ``grokcore.security`` in July 2008 by factoring
security-related components, grokkers and directives out of Grok.
Raw data
{
"_id": null,
"home_page": "https://github.com/zopefoundation/grokcore.security",
"name": "grokcore.security",
"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/7f/24/e41df3e8451d290f95ed308a20521074a3be188470c780405509486632da/grokcore.security-4.0.tar.gz",
"platform": null,
"description": "This package provides basic elements for defining Zope permissions and\nsecurity checkers without ZCML.\n\n.. contents::\n\nSetting up ``grokcore.security``\n================================\n\nThis package is essentially set up like the `grokcore.component`_\npackage, please refer to its documentation for details. The\nadditional ZCML lines you will need are::\n\n <include package=\"grokcore.security\" file=\"meta.zcml\" />\n <include package=\"grokcore.security\" />\n\nPut this somewhere near the top of your root ZCML file but below the\nline where you include ``grokcore.component``'s configuration.\n\n\nDefining permissions\n====================\n\nIn `grokcore.component`_, various components are defined (and\nautomatically registered) by subclassing from certain baseclasses.\nThe same applies to defining permissions with ``grokcore.security`` as\nwell::\n\n import grokcore.security\n\n class EditContent(grokcore.security.Permission):\n grokcore.security.name('mypkg.EditContent')\n\nThis defines a permission with the ID ``mypkg.EditContent``. You must\nalways specify this ID explicitly. In addition, you can also give the\npermission a human-readable title and description. This is useful\nwhen your application provides lists of permissions somewhere and you\ndon't want to bother users with deciphering the dotted IDs::\n\n import grokcore.security\n\n class EditContent(grokcore.security.Permission):\n grokcore.security.name('mypkg.EditContent')\n grokcore.security.title('Edit content')\n grokcore.security.description('Anyone who has this permission may '\n 'modify content in the application.')\n\n\nDefining checkers for components\n================================\n\n``grokcore.security`` provides some means for defining checkers for\ncomponents:\n\n* ``grokcore.security.require(permission)`` which can be used either\n as a class-level directive to set a permission for a whole\n component, or as a decorator to set a permission for a function or\n method.\n\n* ``protect_getattr`` and ``protect_setattr``, available from\n ``grokcore.security.util``, which take a class, an attribute name\n and a permission as arguments and define Zope security checkers for\n getting or setting a particular attribute on instance of said class.\n\nWith these, you can build grokkers for components that need security\ndeclarations. For instance, the `grokcore.view`_ package uses them to\ndefine a grokker that makes security declarations for views::\n\n class ViewSecurityGrokker(martian.ClassGrokker):\n martian.component(grokcore.view.View)\n martian.directive(grokcore.security.require, name='permission')\n\n def execute(self, factory, config, permission, **kw):\n for method_name in zope.publisher.interfaces.browser.IBrowserPage:\n config.action(\n discriminator=('protectName', factory, method_name),\n callable=grokcore.security.util.protect_getattr,\n args=(factory, method_name, permission),\n )\n return True\n\nWith such a grokker, it is possible to protect views like so::\n\n class Edit(grokcore.view.View):\n grokcore.security.require(EditContent)\n\nNote how we can simply pass a permission class to the ``require``\ndirective. Alternatively, you can pass the permission ID::\n\n class Edit(grokcore.view.View):\n grokcore.security.require('mypkg.EditContent')\n\nIf you wanted to be able to define permissions for individual class\nmethods rather than the whole class, you would simply base your\ngrokker on ``martian.MethodGrokker`` rather than ``ClassGrokker``.\nThe actual mechanics of defining a checker are the same.\n\nPlease note that ``grokcore.security`` does not yet provide directives\nthat allow you to specify permissions for simple attribute access\n(read and write).\n\n\nAPI overview\n============\n\n``Permission``\n Base class for defining permissions. Use the ``name`` directive\n to define the mandatory permission ID. Optionally use the\n ``title`` and ``description`` directives to give the permission\n human-readable information.\n\n``Public``\n Special permission that can be referred to whenever a component\n should not be protected by a permission at all (public access).\n\n``require(permission_class_or_id)``\n declares that the use of a particular component (when used as a\n class-level directive) or a method (when used as a method\n decorator) requires a certain permission. The argument can either\n be a permission class (subclass of ``Permission``) or a permission\n ID.\n\nIn addition, the ``grokcore.security`` package exposes the\n`grokcore.component`_ API.\n\n\n.. _grokcore.component: http://pypi.python.org/pypi/grokcore.component\n.. _grokcore.view: http://pypi.python.org/pypi/grokcore.view\n\nChanges\n=======\n\n4.0 (2023-07-11)\n----------------\n\n- Add support for Python 3.7, 3.8, 3.9, 3.10, 3.11.\n\n- Drop support for Python 2.7, 3.4, 3.5, 3.6.\n\n\n3.0.1 (2018-01-12)\n------------------\n\n- Rearrange tests such that Travis CI can pick up all functional tests too.\n\n3.0.0 (2018-01-05)\n------------------\n\n- Fix several test error that came to light.\n\n1.7 (2018-01-03)\n----------------\n\n- Python 3 compatibility.\n\n1.6.3 (2016-01-29)\n------------------\n\n- Update tests.\n\n1.6.2 (2012-05-07)\n------------------\n\n- Properly declare zope.dottedname as a dependency.\n\n1.6.1 (2012-05-02)\n------------------\n\n- Fix the package to properly work if the extra ``role`` is not\n specified.\n\n1.6 (2012-05-01)\n----------------\n\n- The Permission and Role components moved from the grok package to the\n grokcore.security package where it belongs.\n\n- The permissions() directive moved from the grok package to\n grokcore.security where it belongs.\n\n1.5 (2010-11-01)\n----------------\n\n- Upped the requirements for martian and grokcore.component.\n\n- Made package comply to zope.org repository policy.\n\n1.4 (2009-12-13)\n----------------\n\n* **note** Backed out the version requirements for\n grokcore.component-2.0 and martian-0.12. These requirements\n stood in the way of further development especially towards\n grok-1.1 based on the ZTK. The 1.3 version should probably\n have been called 2.0 like with grokcore.component.\n\n* Ported setup.py dependency fixes from trunk.\n\n* Use zope.security instead of zope.app.security.\n\n1.3 (2009-09-16)\n----------------\n\n* Use the grok.zope.org/releaseinfo information instead of our own\n copy of ``versions.cfg``, for easier maintenance.\n\n* Depend on grokcore.component 2.0 and the 0.12 Martian - this changes\n inheritance issues but doesn't appear to affect grokcore.security\n itself.\n\n1.2 (2009-09-14)\n----------------\n\n* Changed the default permissions from grok.View to zope.View. There seems no\n particular reason not to use the standard zope.View permission defined\n in zope.app.security.\n\n NOTE: YOU MUST STILL ASSIGN THIS PERMISSION TO USERS IN YOUR\n site.zcml FILE. OTHERWISE YOU DO NOT HAVE ACCESS TO ANY VIEWS.\n\n* Made sure to include zope.app.security configuration as well, as that\n package defines the zope.View permission. Note that in the future this will\n change to zope.security.\n\n* Bring versions.cfg in line with grok 1.0 release candidate\n versions.cfg.\n\n\n1.1 (2009-07-03)\n----------------\n\n* Changed the default permissions from zope.Public to grok.View.\n\n NOTE: YOU MUST ASSIGN THIS PERMISSION TO USERS IN YOUR\n site.zcml FILE. OTHERWISE YOU DO NOT HAVE ACCESS TO ANY VIEWS.\n\n1.0 (2008-08-03)\n----------------\n\n* Created ``grokcore.security`` in July 2008 by factoring\n security-related components, grokkers and directives out of Grok.\n",
"bugtrack_url": null,
"license": "ZPL",
"summary": "Grok-like configuration for Zope security components",
"version": "4.0",
"project_urls": {
"Homepage": "https://github.com/zopefoundation/grokcore.security"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "136af666add6886c75229755cfd22d03dc7a7d7866690800df657bcd74594ca9",
"md5": "f4c231a14fa59920a9028ccc3744fec0",
"sha256": "51f0433e858fec5dcfdd22dfc3284faf39944e5a8c306547e4f2d7e99ce27fb1"
},
"downloads": -1,
"filename": "grokcore.security-4.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "f4c231a14fa59920a9028ccc3744fec0",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 26166,
"upload_time": "2023-07-11T06:24:45",
"upload_time_iso_8601": "2023-07-11T06:24:45.835617Z",
"url": "https://files.pythonhosted.org/packages/13/6a/f666add6886c75229755cfd22d03dc7a7d7866690800df657bcd74594ca9/grokcore.security-4.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "7f24e41df3e8451d290f95ed308a20521074a3be188470c780405509486632da",
"md5": "8674097211c9472fdc6f17692a7e09d8",
"sha256": "f1aafd3ebc31dfcd2e4f8c2ee8df9830cdd936d49ece221ac9199b2642ef9ca6"
},
"downloads": -1,
"filename": "grokcore.security-4.0.tar.gz",
"has_sig": false,
"md5_digest": "8674097211c9472fdc6f17692a7e09d8",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 19235,
"upload_time": "2023-07-11T06:24:48",
"upload_time_iso_8601": "2023-07-11T06:24:48.375849Z",
"url": "https://files.pythonhosted.org/packages/7f/24/e41df3e8451d290f95ed308a20521074a3be188470c780405509486632da/grokcore.security-4.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-07-11 06:24:48",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "zopefoundation",
"github_project": "grokcore.security",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "grokcore.security"
}
JSON
