AARC Entitlement Library
This package provides python classes to create, parse and compare entitlements according to the AARC recommendations G002 and G069.
Installation
Install using pip:
pip install aarc-entitlement
Documentation
The documentation is available at https://aarcentitlement.readthedocs.io.
The G069 recommendation can be found at https://aarc-community.org/guidelines/aarc-g069. (Its deprecated predecessor, G002, is available at https://aarc-community.org/guidelines/aarc-g002)
Examples
Check if a user entitlement permits usage of a service
import aarc_entitlement
# This entitlement is needed to use a service
required = aarc_entitlement.G002("urn:geant:h-df.de:group:aai-admin")
# This entitlement is held by a user who wants to use the service
actual = aarc_entitlement.G002("urn:geant:h-df.de:group:aai-admin:role=member")
# Is the user permitted to use the service, because of its entitlement `actual`?
permitted = actual.satisfies(required)
# -> True here
# Are the two entitlements the same?
equals = required == actual
# -> False here
G069 Entitlement Normalization
Starting with recommendation G069 the specification requires normalization of entitlements. When using AarcEntitlementG069 the library produces normalized representations.
import aarc_entitlement
not_normalized = "UrN:NiD:ExAmPlE.oRg:group:Minun%20Ryhm%c3%a4ni"
normalized = repr(aarc_entitlement.G069(not_normalized))
# -> "urn:nid:example.org:group:Minun%20Ryhm%C3%A4ni"
Tests, Linting and Documentation
Run tests for all supported python versions:
# run tests, coverage and linter
tox
# build docs
tox -e docs
# After this, the documentation should be located at `doc/build/index.html`.
Packaging
To upload a new package version to pypi use the Makefile:
# build the package
make dist
# upload the package to pypi
make upload
Funding Notice
The AARC project has received funding from the European Union’s Horizon 2020 research and innovation programme under grant agreement No 653965 and 730941.
API
Check entitlements according to the AARC recommendations G002 and G069.
The documentation is available at https://aarcentitlement.readthedocs.io.
The G002 is available at https://aarc-community.org/guidelines/aarc-g002. The G069 is available at https://aarc-community.org/guidelines/aarc-g069.
This code is distributed under the MIT License.
- exception Error
Bases:
Exception
A generic error for this module
- KEYS_ALL = ['namespace_id', 'delegated_namespace', 'subnamespaces', 'group', 'subgroups', 'role', 'group_authority']
All possible keys of entitlement parts
- KEYS_OPTIONAL = ['subnamespaces', 'role', 'subgroups', 'group_authority']
parts with these keys are optional
- KEYS_TUPLES = ['subnamespaces', 'subgroups']
parts with these keys must be tuples or lists
- class Base(entitlement, parse_opts=None)
Bases:
object
Base is the parent class of the actual entitlements. Use
G069
orG002
directly.Instances can be tested for equality and less-than-or-equality.
satisfies()
can be used to check if a user with an entitlement user_has is permitted to use a resource which requires a certain entitlement service_wants using: user_has.satisfies(resource_wants)- Parameters
entitlement (Union[str,dict]) – Usually a raw string representation of the entitlement. Alternatively a dict with the needed parts may be provided.
- Raises
ParseError – If the raw entitlement is not following the respective AARC recommendation and cannnot be parsed.
Error – If the attributes extracted from the entitlement could not be assigned to this instance.
- satisfies(required)
Check if self satisfies the demands of required. self satisfies the requirement if it is equal to or more permissive than required.
- Parameters
required – An entitlement which is required e.g. for using a service.
- Returns
True, if the requirement is satisfied. Otherwise, False is returned.
- is_contained_in(other)
self is contained in other if other is equal or more permissive than `self
- property parts: dict
- Return type
dict
- Returns
A copy of the parts of the entitlement. This cannot be used to modify the entitlement. Use
set_part()
instead.
- get_part(key)
- Return type
Union
[tuple
,str
,None
]- Returns
Entitlement part indicated by key
- set_part(key, value)
set_part can be used to modify this entitlement. Values will be properly normalized.
- Parameters
key (str) – Key of the entitlement part. Valid values can be found in aarc_entitlement.ALL_KEYS
value (Union[tuple, list, str, None]) – The value to be set. If None and the part indicated by key is optional, then the part is deleted.
- class G002(entitlement, strict=False)
Bases:
Base
Create, parse and compare AARC Entitlements G002
Reference specification: https://aarc-community.org/guidelines/aarc-g002
The entitlement is always ‘%xx’ decoded before parsing.
In addition to the parameters from :class:`` the strict parametr is available:
- Parameters
strict (bool,optional) – If set to true, only entitlements with a group_authority part are valid. If raw does not contain a group_authority part, a
ParseError
will be raised.