ch_api.types.shared

Shared data types and utilities for Companies House API responses.

This module contains Pydantic models and utilities used across multiple API response types, providing common patterns and reusable components.

Shared Components

• :class:`LinksSection` - Links to related API resources in responses

These types are used by multiple API response models to represent common elements like resource links.

Example

Access links from an API response:

company = await client.get_company_profile("09370755")
if company.links and company.links.self:
    print(f"Company profile: {company.links.self}")

See also

ch_api.types.base

Base model configuration

ch_api.types.public_data

Models using these shared types

class ch_api.types.shared.LinksSection(**extra_data: Any)

Links to related API resources in response objects.

This model represents the _links section commonly found in Companies House API responses. It provides convenient access to related resource endpoints via the self link and other related links.

The model allows arbitrary link properties to be added, accommodating various API response structures that include different sets of links.

Example

Access links from an API response:

company = await client.get_company_profile("09370755")

# Get the self link
if company.links:
    self_url = company.links.self
    print(f"Self: {self_url}")

    # Get custom link by name
    custom_link = company.links.get_link("company")
    if custom_link:
        print(f"Company: {custom_link}")

Properties

selfstr | None

The URL of the current resource. Read-only property that retrieves the ‘self’ link from the links section.

Note

The _links section in API responses is included as links in the Python models for consistency with Python naming conventions (avoiding leading underscores for public attributes).

See also

pydantic.BaseModel

Parent Pydantic model

model_config = {'extra': 'allow'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

property self: str | None

Get the ‘self’ link from the links section.

This property provides convenient access to the self link, which points to the current resource in the API.

Returns:

The URL of the ‘self’ link if it exists, otherwise None. The URL typically starts with https://api.company-information.service.gov.uk/

Return type:

str | None

Example

Get the self link:

>>> from ch_api.types.shared import LinksSection
>>> links = LinksSection(self="https://api.company-information.service.gov.uk/company/09370755")
>>> if links and links.self:
...     url = links.self
...     print(f"Resource: {url}")
Resource: https://api.company-information.service.gov.uk/company/09370755

get_link(name: str) → str | None

Get a link by name from the links section.

Retrieves a specific link from the response’s _links section by name. This allows accessing both standard links (like ‘self’) and API-specific links defined in the response.

Parameters:

name (str) –

The name of the link to retrieve. Standard link names include:

• self - The current resource

• company - The company resource

• officer - The officer resource

• And other resource-specific links

Returns:

The URL of the requested link if it exists in the response, otherwise None. URLs are typically full HTTPS paths to API endpoints.

Return type:

str | None

Example

Get various links:

links = response.links
self_url = links.get_link("self")
company_url = links.get_link("company")

Note

This method uses Pydantic’s __pydantic_extra__ to access dynamically defined link fields that aren’t explicitly declared in the model.

See also

self

Property for getting the ‘self’ link

__pydantic_fields_set__

The names of fields explicitly set during instantiation.

__pydantic_extra__

A dictionary containing extra values, if [extra][pydantic.config.ConfigDict.extra] is set to ‘allow’.

__pydantic_private__

Values of private attributes set on the model instance.

__class_vars__ = {}

The names of the class variables defined on the model.

__private_attributes__ = {}

Metadata about the private attributes of the model.

__pydantic_complete__ = True

Whether model building is completed, or if there are still undefined fields.

__pydantic_computed_fields__ = {}

A dictionary of computed field names and their corresponding [ComputedFieldInfo][pydantic.fields.ComputedFieldInfo] objects.

__pydantic_core_schema__ = {'cls': <class 'ch_api.types.shared.LinksSection'>, 'config': {'extra_fields_behavior': 'allow', 'title': 'LinksSection'}, 'custom_init': False, 'metadata': {'pydantic_js_functions': [<bound method BaseModel.__get_pydantic_json_schema__ of <class 'ch_api.types.shared.LinksSection'>>]}, 'ref': 'ch_api.types.shared.LinksSection:94287132880912', 'root_model': False, 'schema': {'computed_fields': [], 'fields': {}, 'model_name': 'LinksSection', 'type': 'model-fields'}, 'type': 'model'}

The core schema of the model.

__pydantic_custom_init__ = False

Whether the model has a custom __init__ method.

__pydantic_decorators__ = DecoratorInfos(validators={}, field_validators={}, root_validators={}, field_serializers={}, model_serializers={}, model_validators={}, computed_fields={})

Metadata containing the decorators defined on the model. This replaces Model.__validators__ and Model.__root_validators__ from Pydantic V1.

__pydantic_fields__ = {}

A dictionary of field names and their corresponding [FieldInfo][pydantic.fields.FieldInfo] objects. This replaces Model.__fields__ from Pydantic V1.

__pydantic_generic_metadata__ = {'args': (), 'origin': None, 'parameters': ()}

Metadata for generic models; contains data used for a similar purpose to __args__, __origin__, __parameters__ in typing-module generics. May eventually be replaced by these.

__pydantic_parent_namespace__ = None

Parent namespace of the model, used for automatic rebuilding of models.

__pydantic_post_init__ = None

The name of the post-init method for the model, if defined.

__pydantic_serializer__ = SchemaSerializer(serializer=Model(     ModelSerializer {         class: Py(             0x000055c0ef0ff010,         ),         serializer: Fields(             GeneralFieldsSerializer {                 fields: {},                 computed_fields: Some(                     ComputedFields(                         [],                     ),                 ),                 mode: ModelExtra,                 extra_serializer: None,                 filter: SchemaFilter {                     include: None,                     exclude: None,                 },                 required_fields: 0,             },         ),         has_extra: true,         root_model: false,         name: "LinksSection",     }, ), definitions=[])

The pydantic-core SchemaSerializer used to dump instances of the model.

__pydantic_setattr_handlers__ = {}

__setattr__ handlers. Memoizing the handlers leads to a dramatic performance improvement in __setattr__

__pydantic_validator__ = SchemaValidator(title="LinksSection", validator=Model(     ModelValidator {         revalidate: Never,         validator: ModelFields(             ModelFieldsValidator {                 fields: [],                 model_name: "LinksSection",                 extra_behavior: Allow,                 extras_validator: None,                 extras_keys_validator: None,                 strict: false,                 from_attributes: false,                 loc_by_alias: true,                 validate_by_alias: None,                 validate_by_name: None,             },         ),         class: Py(             0x000055c0ef0ff010,         ),         generic_origin: None,         post_init: None,         frozen: false,         custom_init: false,         root_model: false,         undefined: Py(             0x00007f70cd6e8550,         ),         name: "LinksSection",     }, ), definitions=[], cache_strings=True)

The pydantic-core SchemaValidator used to validate instances of the model.

__signature__ = <Signature (**extra_data: Any) -> None>

The synthesized __init__ [Signature][inspect.Signature] of the model.