Entities

Provide a way of representing the entities of a rule system.

class openfisca_core.entities.CoreEntity(*_CoreEntity__args, **_CoreEntity__kwargs)[source]

Base class to build entities from.

Parameters:
  • *__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)
static check_role_validity(role)[source]

Check if role is an instance of Role.

Parameters:

role (object) – Any object.

Raises:

ValueError – When role is not a Role.

Return type:

None

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_variable_defined_for_entity(variable_name)[source]

Check if variable_name is defined for self.

Parameters:

variable_name (NewType(VariableName, str)) – The Variable to be found.

Raises:

ValueError – When the Variable exists but is defined for another Entity.

Return type:

None

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")
doc: str

A full description.

get_variable(variable_name, check_existence=False)[source]

Get variable_name from variables.

Parameters:
  • variable_name (NewType(VariableName, str)) – The Variable to be found.

  • check_existence (bool) – Was the Variable found?

Returns:
  • Variable – When the Variable exists.

  • None – When the Variable doesn’t exist.

Raises:
  • ValueError – When the _tax_benefit_system is not set yet.

  • ValueError – When check_existence is True and the Variable doesn’t exist.

Return type:

Variable | None

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 ...>
is_person: ClassVar[bool]

Whether the CoreEntity is a person or not.

key: NewType(EntityKey, str)

A key to identify the CoreEntity.

label: str

A summary description.

plural: NewType(EntityPlural, str)

The key pluralised.

set_tax_benefit_system(tax_benefit_system)[source]

A CoreEntity belongs to a TaxBenefitSystem.

Return type:

None

class openfisca_core.entities.Entity(key, plural, label, doc)[source]

An entity (e.g. a person, a household) on which calculations can be run.

Parameters:
  • key (str) – A key to identify the Entity.

  • plural (str) – The key pluralised.

  • label (str) – A summary description.

  • doc (str) – A full description.

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)'
static check_role_validity(role)

Check if role is an instance of Role.

Parameters:

role (object) – Any object.

Raises:

ValueError – When role is not a Role.

Return type:

None

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_variable_defined_for_entity(variable_name)

Check if variable_name is defined for self.

Parameters:

variable_name (NewType(VariableName, str)) – The Variable to be found.

Raises:

ValueError – When the Variable exists but is defined for another Entity.

Return type:

None

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")
doc: str

A full description.

get_variable(variable_name, check_existence=False)

Get variable_name from variables.

Parameters:
  • variable_name (NewType(VariableName, str)) – The Variable to be found.

  • check_existence (bool) – Was the Variable found?

Returns:
  • Variable – When the Variable exists.

  • None – When the Variable doesn’t exist.

Raises:
  • ValueError – When the _tax_benefit_system is not set yet.

  • ValueError – When check_existence is True and the Variable doesn’t exist.

Return type:

Variable | None

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 ...>
is_person: ClassVar[bool] = True

Whether the Entity is a person or not.

key: NewType(EntityKey, str)

A key to identify the Entity.

label: str

A summary description.

plural: NewType(EntityPlural, str)

The key pluralised.

set_tax_benefit_system(tax_benefit_system)

A CoreEntity belongs to a TaxBenefitSystem.

Return type:

None

class openfisca_core.entities.GroupEntity(key, plural, label, doc, roles, containing_entities=())[source]

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.

Parameters:
  • 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)'
static check_role_validity(role)

Check if role is an instance of Role.

Parameters:

role (object) – Any object.

Raises:

ValueError – When role is not a Role.

Return type:

None

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_variable_defined_for_entity(variable_name)

Check if variable_name is defined for self.

Parameters:

variable_name (NewType(VariableName, str)) – The Variable to be found.

Raises:

ValueError – When the Variable exists but is defined for another Entity.

Return type:

None

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")
doc: str

A full description.

get_variable(variable_name, check_existence=False)

Get variable_name from variables.

Parameters:
  • variable_name (NewType(VariableName, str)) – The Variable to be found.

  • check_existence (bool) – Was the Variable found?

Returns:
  • Variable – When the Variable exists.

  • None – When the Variable doesn’t exist.

Raises:
  • ValueError – When the _tax_benefit_system is not set yet.

  • ValueError – When check_existence is True and the Variable doesn’t exist.

Return type:

Variable | None

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 ...>
is_person: ClassVar[bool] = False

Whether the entity is a person or not.

key: NewType(EntityKey, str)

A key to identify the Entity.

label: str

A summary description.

plural: NewType(EntityPlural, str)

The key pluralised.

roles: Iterable[Role]

The list of roles of the GroupEntity.

set_tax_benefit_system(tax_benefit_system)

A CoreEntity belongs to a TaxBenefitSystem.

Return type:

None

class openfisca_core.entities.Role(description, entity)[source]

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.

Parameters:
  • 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: _Description

A description of the Role.

property doc: None | str

A full description, non-indented.

entity: GroupEntity

The GroupEntity the Role belongs to.

property key: RoleKey

A key to identify the Role.

property label: None | str

A summary description.

max: None | int = None

Max number of members.

property plural: None | RolePlural

The key pluralised.

subroles: None | Iterable[Role] = None

A list of subroles.

openfisca_core.entities.SingleEntity

alias of Entity

openfisca_core.entities.build_entity(key, plural, label, doc='', roles=None, is_person=False, *, class_override=None, containing_entities=())[source]

Build an Entity or a GroupEntity.

Parameters:
  • 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.

Returns:
  • Entity – When is_person is True.

  • GroupEntity – When is_person is False.

Raises:

NotImplementedError – If roles is None.

Return type:

SingleEntity | GroupEntity

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
openfisca_core.entities.check_role_validity(role)

Check if role is an instance of Role.

Parameters:

role (object) – Any object.

Raises:

ValueError – When role is not a Role.

Return type:

None

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
openfisca_core.entities.find_role(roles, key, *, total=None)[source]

Find a Role in a GroupEntity.

Parameters:
  • roles (Iterable[Role]) – The roles to search.

  • key (NewType(RoleKey, str)) – The key of the role to find.

  • total (None | int) – The max attribute of the role to find.

Returns:
  • Role – The role if found

  • None – Else None.

Return type:

None | Role

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)