Provide a way of representing the entities of a rule system.
Base class to build entities from.
*__args – Any arguments.
**__kwargs – Any keyword arguments.
Examples
>>> from openfisca_core import entities
>>> from openfisca_core.entities import types as t
>>> class Entity(entities.CoreEntity):
... def __init__(self, key):
... self.key = t.EntityKey(key)
>>> Entity("individual")
Entity(individual)
Check if role
is an instance of Role
.
role (object
) – Any object.
ValueError – When role
is not a Role
.
Examples
>>> from openfisca_core import entities
>>> role = entities.Role({"key": "key"}, object())
>>> entities.check_role_validity(role)
>>> entities.check_role_validity("hey!")
Traceback (most recent call last):
ValueError: hey! is not a valid role
Check if variable_name
is defined for self
.
variable_name (NewType
(VariableName
, str
)) – The Variable
to be found.
ValueError – When the Variable
exists but is defined
for another Entity
.
Examples
>>> from openfisca_core import (
... entities,
... periods,
... taxbenefitsystems,
... variables,
... )
>>> this = entities.SingleEntity("this", "", "", "")
>>> that = entities.SingleEntity("that", "", "", "")
>>> tax_benefit_system = taxbenefitsystems.TaxBenefitSystem([that])
>>> this.set_tax_benefit_system(tax_benefit_system)
>>> this.check_variable_defined_for_entity("tax")
Traceback (most recent call last):
VariableNotFoundError: You tried to calculate or to set a value...
>>> class tax(variables.Variable):
... definition_period = periods.WEEK
... value_type = int
... entity = that
>>> this._tax_benefit_system.add_variable(tax)
<openfisca_core.entities._core_entity.tax object at ...>
>>> this.check_variable_defined_for_entity("tax")
Traceback (most recent call last):
ValueError: You tried to compute the variable 'tax' for the enti...
>>> tax.entity = this
>>> this._tax_benefit_system.update_variable(tax)
<openfisca_core.entities._core_entity.tax object at ...>
>>> this.check_variable_defined_for_entity("tax")
Get variable_name
from variables
.
Variable – When the Variable
exists.
None – When the Variable
doesn’t exist.
ValueError – When the _tax_benefit_system
is not set yet.
ValueError – When check_existence
is True
and
the Variable
doesn’t exist.
Examples
>>> from openfisca_core import (
... entities,
... periods,
... taxbenefitsystems,
... variables,
... )
>>> this = entities.SingleEntity("this", "", "", "")
>>> that = entities.SingleEntity("that", "", "", "")
>>> this.get_variable("tax")
Traceback (most recent call last):
ValueError: You must set 'tax_benefit_system' before calling thi...
>>> tax_benefit_system = taxbenefitsystems.TaxBenefitSystem([this])
>>> this.set_tax_benefit_system(tax_benefit_system)
>>> this.get_variable("tax")
>>> this.get_variable("tax", check_existence=True)
Traceback (most recent call last):
VariableNotFoundError: You tried to calculate or to set a value...
>>> class tax(variables.Variable):
... definition_period = periods.MONTH
... value_type = float
... entity = that
>>> this._tax_benefit_system.add_variable(tax)
<openfisca_core.entities._core_entity.tax object at ...>
>>> this.get_variable("tax")
<openfisca_core.entities._core_entity.tax object at ...>
An entity (e.g. a person, a household) on which calculations can be run.
Examples
>>> from openfisca_core import entities
>>> entity = entities.SingleEntity(
... "individual",
... "individuals",
... "An individual",
... "\t\t\tThe minimal legal entity on which a rule might be a...",
... )
>>> repr(entities.SingleEntity)
"<class 'openfisca_core.entities.entity.Entity'>"
>>> repr(entity)
'Entity(individual)'
>>> str(entity)
'Entity(individual)'
Check if role
is an instance of Role
.
role (object
) – Any object.
ValueError – When role
is not a Role
.
Examples
>>> from openfisca_core import entities
>>> role = entities.Role({"key": "key"}, object())
>>> entities.check_role_validity(role)
>>> entities.check_role_validity("hey!")
Traceback (most recent call last):
ValueError: hey! is not a valid role
Check if variable_name
is defined for self
.
variable_name (NewType
(VariableName
, str
)) – The Variable
to be found.
ValueError – When the Variable
exists but is defined
for another Entity
.
Examples
>>> from openfisca_core import (
... entities,
... periods,
... taxbenefitsystems,
... variables,
... )
>>> this = entities.SingleEntity("this", "", "", "")
>>> that = entities.SingleEntity("that", "", "", "")
>>> tax_benefit_system = taxbenefitsystems.TaxBenefitSystem([that])
>>> this.set_tax_benefit_system(tax_benefit_system)
>>> this.check_variable_defined_for_entity("tax")
Traceback (most recent call last):
VariableNotFoundError: You tried to calculate or to set a value...
>>> class tax(variables.Variable):
... definition_period = periods.WEEK
... value_type = int
... entity = that
>>> this._tax_benefit_system.add_variable(tax)
<openfisca_core.entities._core_entity.tax object at ...>
>>> this.check_variable_defined_for_entity("tax")
Traceback (most recent call last):
ValueError: You tried to compute the variable 'tax' for the enti...
>>> tax.entity = this
>>> this._tax_benefit_system.update_variable(tax)
<openfisca_core.entities._core_entity.tax object at ...>
>>> this.check_variable_defined_for_entity("tax")
Get variable_name
from variables
.
Variable – When the Variable
exists.
None – When the Variable
doesn’t exist.
ValueError – When the _tax_benefit_system
is not set yet.
ValueError – When check_existence
is True
and
the Variable
doesn’t exist.
Examples
>>> from openfisca_core import (
... entities,
... periods,
... taxbenefitsystems,
... variables,
... )
>>> this = entities.SingleEntity("this", "", "", "")
>>> that = entities.SingleEntity("that", "", "", "")
>>> this.get_variable("tax")
Traceback (most recent call last):
ValueError: You must set 'tax_benefit_system' before calling thi...
>>> tax_benefit_system = taxbenefitsystems.TaxBenefitSystem([this])
>>> this.set_tax_benefit_system(tax_benefit_system)
>>> this.get_variable("tax")
>>> this.get_variable("tax", check_existence=True)
Traceback (most recent call last):
VariableNotFoundError: You tried to calculate or to set a value...
>>> class tax(variables.Variable):
... definition_period = periods.MONTH
... value_type = float
... entity = that
>>> this._tax_benefit_system.add_variable(tax)
<openfisca_core.entities._core_entity.tax object at ...>
>>> this.get_variable("tax")
<openfisca_core.entities._core_entity.tax object at ...>
Represents an entity containing several others with different roles.
A GroupEntity
represents an Entity
containing several other entities,
with different roles, and on which calculations can be run.
key (str
) – A key to identify the GroupEntity
.
plural (str
) – The key
pluralised.
label (str
) – A summary description.
doc (str
) – A full description.
roles (Sequence
[RoleParams
]) – The list of roles of the group entity.
containing_entities (Iterable
[str
]) – The list of keys of group entities whose members
are guaranteed to be a superset of this group’s entities.
Examples
>>> from openfisca_core import entities
>>> family_roles = [
... {
... "key": "parent",
... "subroles": ["first_parent", "second_parent"],
... }
... ]
>>> family = entities.GroupEntity(
... "family",
... "families",
... "A family",
... "\t\t\tAll the people somehow related living together.",
... family_roles,
... )
>>> household_roles = [
... {
... "key": "partners",
... "subroles": ["first_partner", "second_partner"],
... }
... ]
>>> household = entities.GroupEntity(
... "household",
... "households",
... "A household",
... "\t\t\tAll the people who live together in the same place.",
... household_roles,
... (family.key,),
... )
>>> repr(entities.GroupEntity)
"<class 'openfisca_core.entities.group_entity.GroupEntity'>"
>>> repr(household)
'GroupEntity(household)'
>>> str(household)
'GroupEntity(household)'
Check if role
is an instance of Role
.
role (object
) – Any object.
ValueError – When role
is not a Role
.
Examples
>>> from openfisca_core import entities
>>> role = entities.Role({"key": "key"}, object())
>>> entities.check_role_validity(role)
>>> entities.check_role_validity("hey!")
Traceback (most recent call last):
ValueError: hey! is not a valid role
Check if variable_name
is defined for self
.
variable_name (NewType
(VariableName
, str
)) – The Variable
to be found.
ValueError – When the Variable
exists but is defined
for another Entity
.
Examples
>>> from openfisca_core import (
... entities,
... periods,
... taxbenefitsystems,
... variables,
... )
>>> this = entities.SingleEntity("this", "", "", "")
>>> that = entities.SingleEntity("that", "", "", "")
>>> tax_benefit_system = taxbenefitsystems.TaxBenefitSystem([that])
>>> this.set_tax_benefit_system(tax_benefit_system)
>>> this.check_variable_defined_for_entity("tax")
Traceback (most recent call last):
VariableNotFoundError: You tried to calculate or to set a value...
>>> class tax(variables.Variable):
... definition_period = periods.WEEK
... value_type = int
... entity = that
>>> this._tax_benefit_system.add_variable(tax)
<openfisca_core.entities._core_entity.tax object at ...>
>>> this.check_variable_defined_for_entity("tax")
Traceback (most recent call last):
ValueError: You tried to compute the variable 'tax' for the enti...
>>> tax.entity = this
>>> this._tax_benefit_system.update_variable(tax)
<openfisca_core.entities._core_entity.tax object at ...>
>>> this.check_variable_defined_for_entity("tax")
Get variable_name
from variables
.
Variable – When the Variable
exists.
None – When the Variable
doesn’t exist.
ValueError – When the _tax_benefit_system
is not set yet.
ValueError – When check_existence
is True
and
the Variable
doesn’t exist.
Examples
>>> from openfisca_core import (
... entities,
... periods,
... taxbenefitsystems,
... variables,
... )
>>> this = entities.SingleEntity("this", "", "", "")
>>> that = entities.SingleEntity("that", "", "", "")
>>> this.get_variable("tax")
Traceback (most recent call last):
ValueError: You must set 'tax_benefit_system' before calling thi...
>>> tax_benefit_system = taxbenefitsystems.TaxBenefitSystem([this])
>>> this.set_tax_benefit_system(tax_benefit_system)
>>> this.get_variable("tax")
>>> this.get_variable("tax", check_existence=True)
Traceback (most recent call last):
VariableNotFoundError: You tried to calculate or to set a value...
>>> class tax(variables.Variable):
... definition_period = periods.MONTH
... value_type = float
... entity = that
>>> this._tax_benefit_system.add_variable(tax)
<openfisca_core.entities._core_entity.tax object at ...>
>>> this.get_variable("tax")
<openfisca_core.entities._core_entity.tax object at ...>
The role of an Entity
within a GroupEntity
.
Each Entity
related to a GroupEntity
has a Role
. For example,
if you have a family, its roles could include a parent, a child, and so on.
Or if you have a tax household, its roles could include the taxpayer, a
spouse, several dependents, and the like.
description (RoleParams
) – A description of the Role.
entity (GroupEntity
) – The Entity to which the Role belongs.
Examples
>>> from openfisca_core import entities
>>> entity = entities.GroupEntity("key", "plural", "label", "doc", [])
>>> role = entities.Role({"key": "parent"}, entity)
>>> repr(entities.Role)
"<class 'openfisca_core.entities.role.Role'>"
>>> repr(role)
'Role(parent)'
>>> str(role)
'Role(parent)'
>>> {role}
{Role(parent)}
>>> role.key
'parent'
_Description
¶A description of the Role
.
GroupEntity
¶The GroupEntity
the Role belongs to.
The key
pluralised.
Build an Entity
or a GroupEntity
.
key (str
) – Key to identify the Entity
or GroupEntity
.
plural (str
) – The key
pluralised.
label (str
) – A summary description.
doc (str
) – A full description.
roles (None
| Sequence
[RoleParams
]) – A list of roles —if it’s a GroupEntity
.
is_person (bool
) – If is an individual, or not.
class_override (object
) –
?
containing_entities (Sequence
[str
]) – Keys of contained entities.
Entity – When is_person
is True
.
GroupEntity – When is_person
is False
.
NotImplementedError – If roles
is None
.
Examples
>>> from openfisca_core import entities
>>> entity = entities.build_entity(
... "syndicate",
... "syndicates",
... "Banks loaning jointly.",
... roles=[],
... containing_entities=(),
... )
>>> entity
GroupEntity(syndicate)
>>> entities.build_entity(
... "company",
... "companies",
... "A small or medium company.",
... is_person=True,
... )
Entity(company)
>>> role = entities.Role({"key": "key"}, entity)
>>> entities.build_entity(
... "syndicate",
... "syndicates",
... "Banks loaning jointly.",
... roles=[role],
... )
Traceback (most recent call last):
TypeError: 'Role' object is not subscriptable
Check if role
is an instance of Role
.
role (object
) – Any object.
ValueError – When role
is not a Role
.
Examples
>>> from openfisca_core import entities
>>> role = entities.Role({"key": "key"}, object())
>>> entities.check_role_validity(role)
>>> entities.check_role_validity("hey!")
Traceback (most recent call last):
ValueError: hey! is not a valid role
Find a Role
in a GroupEntity
.
Role – The role if found
None – Else None
.
Examples
>>> from openfisca_core import entities
>>> from openfisca_core.entities import types as t
>>> principal = t.RoleParams(
... key="principal",
... label="Principal",
... doc="Person focus of a calculation in a family context.",
... max=1,
... )
>>> partner = t.RoleParams(
... key="partner",
... plural="partners",
... label="Partners",
... doc="Persons partners of the principal.",
... )
>>> parent = t.RoleParams(
... key="parent",
... plural="parents",
... label="Parents",
... doc="Persons parents of children of the principal",
... subroles=["first_parent", "second_parent"],
... )
>>> group_entity = entities.build_entity(
... key="family",
... plural="families",
... label="Family",
... doc="A Family represents a collection of related persons.",
... roles=[principal, partner, parent],
... )
>>> entities.find_role(group_entity.roles, "principal", total=1)
Role(principal)
>>> entities.find_role(group_entity.roles, "partner")
Role(partner)
>>> entities.find_role(group_entity.roles, "parent", total=2)
Role(parent)
>>> entities.find_role(group_entity.roles, "first_parent", total=1)
Role(first_parent)