Bibs, holdings and items¶

Reached as client.bibs, which carries the record, holding and item methods plus sub-namespaces for loans, requests and digital representations.

Most methods here want the full MMS ID / holding ID / item PID path. get_item resolves all three from a barcode, which is usually where to start:

item = await client.bibs.get_item("39001234567890")
mms_id = item.bib_data.mms_id
holding_id = item.holding_data.holding_id
item_pid = item.item_data.pid

Not everything returns a Box

The holding and bib-record methods – get_holding, update_holding, create_holding, get_bib, create_bib, update_bib – exchange raw MARC XML as str, because Alma has no JSON representation of a MARC record. Those methods take no model= argument. See Responses.

`client.bibs`¶

AlmaClientBibNS ¶

AlmaClientBibNS(client: _AlmaExecutable)

Bases: BaseNamespace

Namespace for bibliographic functionality, exposed at client.bibs.

Carries the record, holding and item methods themselves, plus three sub-namespaces:

Attribute	Class
`client.bibs.loans`	`AlmaClientBibLoansNS`
`client.bibs.requests`	`AlmaClientBibRequestsNS`
`client.bibs.representations`	`AlmaClientBibRepresentationsNS`

Start with get_item when all you have is a barcode: it resolves the MMS ID, holding ID and item PID that the other methods need.

The holding and bib-record methods (get_holding, update_holding, create_holding, get_bib, create_bib, update_bib) exchange raw MARC XML as str and take no model= argument. Everything else returns a Box.

get_item `async` Alma: Retrieve Item and label printing information ¶

get_item(
    item_barcode: str, *, model: type[_ModelT]
) -> _ModelT

get_item(
    item_barcode: str, *, model: None = ...
) -> RESP_TYPE

Retrieve an item by its barcode.

The usual entry point into this namespace: given only a barcode, the response carries the MMS ID, holding ID and item PID that the other methods need, along with the bib data and the item's current loan and request state.

Parameters:

Name	Type	Description	Default
`item_barcode`	`str`	The item's barcode.	required
`model`	`Any`	Optional Pydantic model class to validate the response into.	`None`

Returns:

Type	Description
`Any`	The item record, with `bib_data`, `holding_data` and `item_data`.

Raises:

Type	Description
`BarcodeNotFoundError`	If no item has that barcode.
`IllegalBarcodeError`	If the barcode is malformed.

Examples:

item = await client.bibs.get_item("39001234567890")
print(item.bib_data.title)
mms_id = item.bib_data.mms_id
holding_id = item.holding_data.holding_id
item_pid = item.item_data.pid

get_item_by_pid `async` Alma: Retrieve Item and label printing information ¶

get_item_by_pid(
    mms_id: str,
    holding_id: str,
    item_pid: str,
    *,
    model: type[_ModelT],
) -> _ModelT

get_item_by_pid(
    mms_id: str,
    holding_id: str,
    item_pid: str,
    *,
    model: None = ...,
) -> RESP_TYPE

Retrieve an item by its full inventory path.

Use get_item when you have a barcode instead.

Parameters:

Name	Type	Description	Default
`mms_id`	`str`	The MMS ID of the bibliographic record.	required
`holding_id`	`str`	The holding ID the item belongs to.	required
`item_pid`	`str`	The item PID.	required
`model`	`Any`	Optional Pydantic model class to validate the response into.	`None`

Returns:

Type	Description
`Any`	The item record, with `bib_data`, `holding_data` and `item_data`.

Raises:

Type	Description
`MMSIdNotFoundError`	If no record has that MMS ID.
`APIClientError`	If the holding or item does not exist.

Examples:

item = await client.bibs.get_item_by_pid(
    "99123456789012345", "22123456780001234", "23123456770001234"
)

create_item `async` Alma: Create Item ¶

create_item(
    mms_id: str,
    holding_id: str,
    item: Body,
    *,
    generate_description: bool = ...,
    model: type[_ModelT],
) -> _ModelT

create_item(
    mms_id: str,
    holding_id: str,
    item: Body,
    *,
    generate_description: bool = ...,
    model: None = ...,
) -> RESP_TYPE

Create an item under a holding.

Being a POST, this call is not replayed if the response is lost in transit – a retry could create a duplicate item. See Rate limiting.

Parameters:

Name	Type	Description	Default
`mms_id`	`str`	The MMS ID of the bibliographic record.	required
`holding_id`	`str`	The holding ID to create the item under.	required
`item`	`Body`	The item record to create. `item_data.barcode` is normally required. Accepts a mapping or any object implementing `dump`/`model_dump`.	required
`generate_description`	`bool`	Whether Alma should build the item's description from its enumeration and chronology fields.	`False`
`model`	`Any`	Optional Pydantic model class to validate the response into.	`None`

Returns:

Type	Description
`Any`	The newly created item record, including its assigned PID.

Raises:

Type	Description
`MMSIdNotFoundError`	If no record has that MMS ID.
`InvalidCodeError`	If a code in the item – its policy or material type, for instance – is not valid for this institution.
`APIClientError`	If the holding does not exist or the barcode is in use.

Examples:

item = await client.bibs.create_item(
    "99123456789012345",
    "22123456780001234",
    {"item_data": {"barcode": "39001234567890", "policy": {"value": "STANDARD"}}},
)

update_item `async` Alma: Update Item information ¶

update_item(
    mms_id: str,
    holding_id: str,
    item_pid: str,
    item: Body,
    *,
    model: type[_ModelT],
) -> _ModelT

update_item(
    mms_id: str,
    holding_id: str,
    item_pid: str,
    item: Body,
    *,
    model: None = ...,
) -> RESP_TYPE

Update an item.

Alma replaces the whole item, so fetch it with get_item or get_item_by_pid and modify that rather than sending a partial body.

Parameters:

Name	Type	Description	Default
`mms_id`	`str`	The MMS ID of the bibliographic record.	required
`holding_id`	`str`	The holding ID the item belongs to.	required
`item_pid`	`str`	The item PID.	required
`item`	`Body`	The full, modified item record.	required
`model`	`Any`	Optional Pydantic model class to validate the response into.	`None`

Returns:

Type	Description
`Any`	The updated item record.

Raises:

Type	Description
`InvalidCodeError`	If a code in the item is not valid for this institution. Raised in place of the generic `RequestFailedError` so the offending field and value are named in the message.
`MMSIdNotFoundError`	If no record has that MMS ID.
`APIClientError`	If the holding or item does not exist.

Examples:

item = await client.bibs.get_item("39001234567890")
item.item_data.public_note = "Reference only"
await client.bibs.update_item(
    item.bib_data.mms_id,
    item.holding_data.holding_id,
    item.item_data.pid,
    item,
)

withdraw_item `async` Alma: Withdraw Item ¶

withdraw_item(
    mms_id: str,
    holding_id: str,
    item_pid: str,
    *,
    override: bool = False,
    handle_holding: Literal[
        "retain", "delete", "suppress"
    ] = "retain",
    handle_bib: Literal[
        "retain", "delete", "suppress"
    ] = "retain",
) -> None

Withdraw (delete) an item.

handle_holding and handle_bib decide what happens to the now-empty parents. Both default to "retain", which leaves them in place – the conservative choice, and deliberately so: a bib record deleted here is gone along with everything attached to it.

Parameters:

Name	Type	Description	Default
`mms_id`	`str`	The MMS ID of the bibliographic record.	required
`holding_id`	`str`	The holding ID the item belongs to.	required
`item_pid`	`str`	The item PID.	required
`override`	`bool`	Whether to override Alma's warnings, for example when the item is on loan or has outstanding requests.	`False`
`handle_holding`	`Literal['retain', 'delete', 'suppress']`	What to do with the holding if this was its last item – `"retain"`, `"delete"` or `"suppress"`.	`'retain'`
`handle_bib`	`Literal['retain', 'delete', 'suppress']`	What to do with the bib record if this was its last holding.	`'retain'`

Returns:

Type	Description
`None`	`None`. Alma returns an empty body on success.

Raises:

Type	Description
`MMSIdNotFoundError`	If no record has that MMS ID.
`APIClientError`	If the holding or item does not exist, or Alma refuses the withdrawal and `override` is False.

Examples:

await client.bibs.withdraw_item(
    "99123456789012345",
    "22123456780001234",
    "23123456770001234",
    handle_holding="delete",
)

get_items `async` Alma: Retrieve Items list ¶

get_items(
    mms_id: str,
    holding_id: str,
    expand: str | None = ...,
    user_id: str | None = ...,
    limit: int = ...,
    offset: int = ...,
    current_library: str | None = ...,
    current_location: str | None = ...,
    q: str | None = ...,
    order_by: str | None = ...,
    direction: Literal["asc", "desc"] = ...,
    create_date_from: str | None = ...,
    create_date_to: str | None = ...,
    modify_date_from: str | None = ...,
    receive_date_from: str | None = ...,
    receive_date_to: str | None = ...,
    expected_receive_date_from: str | None = ...,
    expected_receive_date_to: str | None = ...,
    view: Literal["brief", "label"] = ...,
    *,
    model: type[_ModelT],
) -> _ModelT

get_items(
    mms_id: str,
    holding_id: str,
    expand: str | None = ...,
    user_id: str | None = ...,
    limit: int = ...,
    offset: int = ...,
    current_library: str | None = ...,
    current_location: str | None = ...,
    q: str | None = ...,
    order_by: str | None = ...,
    direction: Literal["asc", "desc"] = ...,
    create_date_from: str | None = ...,
    create_date_to: str | None = ...,
    modify_date_from: str | None = ...,
    receive_date_from: str | None = ...,
    receive_date_to: str | None = ...,
    expected_receive_date_from: str | None = ...,
    expected_receive_date_to: str | None = ...,
    view: Literal["brief", "label"] = ...,
    *,
    model: None = ...,
) -> RESP_TYPE

List the items under a holding.

Pass holding_id="ALL" to list every item on the record regardless of holding. Arguments left as None are omitted from the query entirely rather than sent empty.

Parameters:

Name	Type	Description	Default
`mms_id`	`str`	The MMS ID of the bibliographic record.	required
`holding_id`	`str`	The holding ID, or `"ALL"` for every holding on the record.	required
`expand`	`str \| None`	Pass `"due_date"` or `"due_date_policy"` to have Alma calculate and include loan information per item.	`None`
`user_id`	`str \| None`	A user identifier to calculate the due-date policy against, used together with `expand`.	`None`
`limit`	`int`	Maximum number of items to return in this page. Note the default here is 10, not 100.	`10`
`offset`	`int`	Index of the first item to return, for paging.	`0`
`current_library`	`str \| None`	Restrict to items currently at this library code.	`None`
`current_location`	`str \| None`	Restrict to items currently in this location code.	`None`
`q`	`str \| None`	Search query, in Alma's `field~value` form.	`None`
`order_by`	`str \| None`	Field to sort by.	`None`
`direction`	`Literal['asc', 'desc']`	Sort direction.	`'desc'`
`create_date_from`	`str \| None`	Earliest creation date, as `YYYY-MM-DD`.	`None`
`create_date_to`	`str \| None`	Latest creation date, as `YYYY-MM-DD`.	`None`
`modify_date_from`	`str \| None`	Earliest modification date, as `YYYY-MM-DD`.	`None`
`receive_date_from`	`str \| None`	Earliest receiving date, as `YYYY-MM-DD`.	`None`
`receive_date_to`	`str \| None`	Latest receiving date, as `YYYY-MM-DD`.	`None`
`expected_receive_date_from`	`str \| None`	Earliest expected receiving date.	`None`
`expected_receive_date_to`	`str \| None`	Latest expected receiving date.	`None`
`view`	`Literal['brief', 'label']`	`"brief"` for the standard item data, `"label"` for the reduced set used when printing spine labels.	`'brief'`
`model`	`Any`	Optional Pydantic model class to validate the response into.	`None`

Returns:

Type	Description
`Any`	A page of items, with `total_record_count` giving the full result size.

Raises:

Type	Description
`MMSIdNotFoundError`	If no record has that MMS ID.
`APIClientError`	If the holding does not exist or a date is malformed.

Examples:

Every item on a record, with due dates:

items = await client.bibs.get_items(
    "99123456789012345", "ALL", expand="due_date", limit=100
)
for item in items.item:
    print(item.item_data.barcode, item.item_data.base_status.desc)

get_portfolios `async` Alma: Retrieve Portfolios list ¶

get_portfolios(
    mms_id: str,
    limit: int = ...,
    offset: int = ...,
    *,
    model: type[_ModelT],
) -> _ModelT

get_portfolios(
    mms_id: str,
    limit: int = ...,
    offset: int = ...,
    *,
    model: None = ...,
) -> RESP_TYPE

List the electronic portfolios on a bibliographic record.

Portfolios are the electronic counterpart to physical items – the individual holdings of an e-resource within a collection.

Parameters:

Name	Type	Description	Default
`mms_id`	`str`	The MMS ID of the bibliographic record.	required
`limit`	`int`	Maximum number of portfolios to return in this page. Note the default here is 10, not 100.	`10`
`offset`	`int`	Index of the first portfolio to return, for paging.	`0`
`model`	`Any`	Optional Pydantic model class to validate the response into.	`None`

Returns:

Type	Description
`Any`	A page of portfolios, with `total_record_count` giving the full result
`Any`	size.

Raises:

Type	Description
`MMSIdNotFoundError`	If no record has that MMS ID.

Examples:

portfolios = await client.bibs.get_portfolios("99123456789012345", limit=100)
for p in portfolios.portfolio:
    print(p.id, p.electronic_collection.value)

get_holding `async` Alma: Retrieve Holdings Record ¶

get_holding(mms_id: str, holding_id: str) -> str

Retrieve a holding record as raw MARC XML.

Returns a str, not a Box – Alma has no JSON representation of a MARC record – and so takes no model= argument. Parse the result with your own MARC or XML library.

Parameters:

Name	Type	Description	Default
`mms_id`	`str`	The MMS ID of the bibliographic record.	required
`holding_id`	`str`	The holding ID.	required

Returns:

Type	Description
`str`	The holding as a MARC XML string.

Raises:

Type	Description
`MMSIdNotFoundError`	If no record has that MMS ID.
`APIClientError`	If the holding does not exist.

Examples:

xml = await client.bibs.get_holding("99123456789012345", "22123456780001234")

update_holding `async` Alma: Update Holdings Record ¶

update_holding(
    mms_id: str, holding_id: str, record: str
) -> str

Replace a holding record with MARC XML.

Takes and returns str, not Box. Alma replaces the whole record, so fetch it with get_holding and edit that XML rather than composing a partial document.

Parameters:

Name	Type	Description	Default
`mms_id`	`str`	The MMS ID of the bibliographic record.	required
`holding_id`	`str`	The holding ID.	required
`record`	`str`	The complete holding record as a MARC XML string.	required

Returns:

Type	Description
`str`	The updated holding as a MARC XML string.

Raises:

Type	Description
`MMSIdNotFoundError`	If no record has that MMS ID.
`APIClientError`	If the holding does not exist, or the XML is malformed or fails Alma's validation.

Examples:

xml = await client.bibs.get_holding("99123456789012345", "22123456780001234")
updated = xml.replace("<subfield code='h'>QA76</subfield>", "<subfield code='h'>QA77</subfield>")
await client.bibs.update_holding("99123456789012345", "22123456780001234", updated)

create_holding `async` Alma: Create holding record ¶

create_holding(mms_id: str, record: str) -> str

Create a holding on a bibliographic record from MARC XML.

Takes and returns str, not Box.

Being a POST, this call is not replayed if the response is lost in transit – a retry could create a duplicate holding. See Rate limiting.

Parameters:

Name	Type	Description	Default
`mms_id`	`str`	The MMS ID of the bibliographic record.	required
`record`	`str`	The holding record as a MARC XML string.	required

Returns:

Type	Description
`str`	The newly created holding as a MARC XML string, including its assigned
`str`	holding ID.

Raises:

Type	Description
`MMSIdNotFoundError`	If no record has that MMS ID.
`APIClientError`	If the XML is malformed or fails Alma's validation.

Examples:

xml = "<holding><record>...</record></holding>"
created = await client.bibs.create_holding("99123456789012345", xml)

delete_holding `async` Alma: Delete Holdings Record ¶

delete_holding(
    mms_id: str,
    holding_id: str,
    *,
    handle_bib: Literal[
        "retain", "delete", "suppress"
    ] = "retain",
) -> None

Delete a holding record.

The holding must have no items left under it. handle_bib defaults to "retain", the conservative choice – deleting the bib record removes everything attached to it.

Parameters:

Name	Type	Description	Default
`mms_id`	`str`	The MMS ID of the bibliographic record.	required
`holding_id`	`str`	The holding ID.	required
`handle_bib`	`Literal['retain', 'delete', 'suppress']`	What to do with the bib record if this was its last holding – `"retain"`, `"delete"` or `"suppress"`.	`'retain'`

Returns:

Type	Description
`None`	`None`. Alma returns an empty body on success.

Raises:

Type	Description
`MMSIdNotFoundError`	If no record has that MMS ID.
`APIClientError`	If the holding does not exist or still has items.

Examples:

await client.bibs.delete_holding("99123456789012345", "22123456780001234")

get_holdings `async` Alma: Retrieve Holdings list ¶

get_holdings(
    mms_id: str, *, model: type[_ModelT]
) -> _ModelT

get_holdings(
    mms_id: str, *, model: None = ...
) -> RESP_TYPE

List the holdings on a bibliographic record.

Unlike the single-holding methods, this one returns a Box and accepts model= – it is a summary list rather than MARC records. Use get_holding for the MARC XML of one holding.

Parameters:

Name	Type	Description	Default
`mms_id`	`str`	The MMS ID of the bibliographic record.	required
`model`	`Any`	Optional Pydantic model class to validate the response into.	`None`

Returns:

Type	Description
`Any`	The record's holdings, each with its ID, library and location.

Raises:

Type	Description
`MMSIdNotFoundError`	If no record has that MMS ID.

Examples:

holdings = await client.bibs.get_holdings("99123456789012345")
for h in holdings.holding:
    print(h.holding_id, h.library.value, h.location.value)

create_bib `async` Alma: Create record ¶

create_bib(
    record: str,
    *,
    from_nz_mms_id: str | None = None,
    from_cz_mms_id: str | None = None,
    normalization: str | None = None,
    validate: bool = False,
    override_warning: bool = False,
    check_match: bool = False,
    import_profile: str | None = None,
) -> str

Create a bib record from the supplied MARC XML.

Parameters:

Name	Type	Description	Default
`record`	`str`	Full MARC XML record to create.	required
`from_nz_mms_id`	`str \| None`	Link the new bib to this Network Zone record.	`None`
`from_cz_mms_id`	`str \| None`	Link the new bib to this Community Zone record.	`None`
`normalization`	`str \| None`	Normalisation process ID to run on the record.	`None`
`validate`	`bool`	Run MARC validation before saving.	`False`
`override_warning`	`bool`	Save despite Alma's validation warnings – which include the duplicate-match warning raised by `check_match`. Defaults to `False`, but is only sent on the wire when it is `True` or when `validate` or `check_match` is on: Alma rejects an explicit `false` outside those cases (error 401873), and with neither check running there is no warning to override anyway.	`False`
`check_match`	`bool`	Run match detection against existing records. Only has an effect while `override_warning` is `False`.	`False`
`import_profile`	`str \| None`	Import profile ID governing the create.	`None`

get_bib `async` Alma: Retrieve Bib ¶

get_bib(
    mms_id: str,
    *,
    view: Literal["full", "brief", "local_fields"] = "full",
    expand_physical: bool = False,
    expand_electronic: bool = False,
    expand_digital: bool = False,
    expand_requests: bool = False,
) -> str

Retrieve a bibliographic record as raw MARC XML.

Returns a str, not a Box – Alma has no JSON representation of a MARC record – and so takes no model= argument.

The expand_* flags append availability information to the record. Each one makes Alma do extra work, so leave off the ones you do not need.

Parameters:

Name	Type	Description	Default
`mms_id`	`str`	The MMS ID of the bibliographic record.	required
`view`	`Literal['full', 'brief', 'local_fields']`	`"full"` for the complete record, `"brief"` for a reduced set of fields, `"local_fields"` for the institution's local fields only.	`'full'`
`expand_physical`	`bool`	Append physical holdings availability (`p_avail`).	`False`
`expand_electronic`	`bool`	Append electronic availability (`e_avail`).	`False`
`expand_digital`	`bool`	Append digital availability (`d_avail`).	`False`
`expand_requests`	`bool`	Append the record's request count.	`False`

Returns:

Type	Description
`str`	The bibliographic record as a MARC XML string.

Raises:

Type	Description
`MMSIdNotFoundError`	If no record has that MMS ID.

Examples:

xml = await client.bibs.get_bib(
    "99123456789012345", expand_physical=True, expand_requests=True
)

update_bib `async` Alma: Update Bib Record ¶

update_bib(
    mms_id: str,
    record: str,
    *,
    normalization: str | None = None,
    validate: bool = False,
    override_warning: bool = False,
    override_lock: bool = False,
    stale_version_check: bool = False,
    cataloguer_level: str | None = None,
    check_match: bool = False,
) -> str

Update a bib record with the supplied MARC XML.

Parameters:

Name	Type	Description	Default
`mms_id`	`str`	MMS ID of the bib to update.	required
`record`	`str`	Full MARC XML record to write.	required
`normalization`	`str \| None`	Normalisation process ID to run on the record.	`None`
`validate`	`bool`	Run MARC validation before saving.	`False`
`override_warning`	`bool`	Save despite Alma's validation warnings. Defaults to `False`, but is only sent on the wire when it is `True` or when `validate` or `check_match` is on – see `create_bib`.	`False`
`override_lock`	`bool`	Save despite another cataloguer holding the record lock, discarding their in-progress edit. Defaults to `False`.	`False`
`stale_version_check`	`bool`	Reject the update if the record changed since it was read.	`False`
`cataloguer_level`	`str \| None`	Cataloguer level to apply to the operation.	`None`
`check_match`	`bool`	Run match detection against existing records.	`False`

delete_bib `async` Alma: Delete Bib Record ¶

delete_bib(
    mms_id: str,
    *,
    override: bool = False,
    cataloguer_level: str | None = None,
) -> None

Delete a bib record.

Parameters:

Name	Type	Description	Default
`mms_id`	`str`	MMS ID of the bib to delete.	required
`override`	`bool`	Delete even when Alma objects – e.g. the bib still has holdings, items or orders attached. Defaults to `False` so the shortest call cannot silently discard inventory.	`False`
`cataloguer_level`	`str \| None`	Cataloguer level to apply to the operation.	`None`

scan_in `async` Alma: Scan-in operation on item. ¶

scan_in(
    mms_id: str,
    holding_id: str,
    item_pid: str,
    *,
    library: str | None = ...,
    department: str | None = ...,
    circ_desk: str | None = ...,
    work_order_type: str | None = ...,
    status: str | None = ...,
    external_id: bool = ...,
    request_id: str | None = ...,
    auto_print_slip: bool = ...,
    place_on_hold_shelf: bool = ...,
    confirm: bool = ...,
    register_in_house_use: bool = ...,
    done: bool = ...,
    model: type[_ModelT],
) -> _ModelT

scan_in(
    mms_id: str,
    holding_id: str,
    item_pid: str,
    *,
    library: str | None = ...,
    department: str | None = ...,
    circ_desk: str | None = ...,
    work_order_type: str | None = ...,
    status: str | None = ...,
    external_id: bool = ...,
    request_id: str | None = ...,
    auto_print_slip: bool = ...,
    place_on_hold_shelf: bool = ...,
    confirm: bool = ...,
    register_in_house_use: bool = ...,
    done: bool = ...,
    model: None = ...,
) -> RESP_TYPE

Scan an item in at a circulation desk or work department.

The API equivalent of passing an item over the desk: returns it if it is on loan, and moves it to its next workflow step – onto the hold shelf, into transit, or back to the shelf.

Supply either circ_desk with library (a circulation desk scan) or department with work_order_type (a work department scan), not both.

Being a POST, this call is not replayed if the response is lost in transit. See Rate limiting.

Parameters:

Name	Type	Description	Default
`mms_id`	`str`	The MMS ID of the bibliographic record.	required
`holding_id`	`str`	The holding ID the item belongs to.	required
`item_pid`	`str`	The item PID.	required
`library`	`str \| None`	Code of the library owning the circulation desk.	`None`
`department`	`str \| None`	Code of the work department scanning the item in.	`None`
`circ_desk`	`str \| None`	Code of the circulation desk scanning the item in.	`None`
`work_order_type`	`str \| None`	The work order type, when scanning into a department.	`None`
`status`	`str \| None`	The work order status to move the item to.	`None`
`external_id`	`bool`	Whether `request_id` is an external identifier rather than an Alma one.	`False`
`request_id`	`str \| None`	Identifier of the request this scan fulfils.	`None`
`auto_print_slip`	`bool`	Whether Alma should generate the transit or hold slip.	`False`
`place_on_hold_shelf`	`bool`	Whether to place the item on the hold shelf for a waiting request.	`False`
`confirm`	`bool`	Whether to confirm Alma's scan-in messages, such as a transit prompt.	`False`
`register_in_house_use`	`bool`	Whether to record the scan as in-house use rather than a return.	`False`
`done`	`bool`	Whether the work order step is complete, releasing the item from the department.	`False`
`model`	`Any`	Optional Pydantic model class to validate the response into.	`None`

Returns:

Type	Description
`Any`	The item record in its post-scan state, including any transit or hold
`Any`	instructions Alma generated.

Raises:

Type	Description
`ScanItemRetrievalError`	If the scan succeeded but Alma did not return the item information (code `402504`).
`MMSIdNotFoundError`	If no record has that MMS ID.
`APIClientError`	If the holding or item does not exist, or the desk, library or department codes are not valid.

Examples:

item = await client.bibs.get_item("39001234567890")
scanned = await client.bibs.scan_in(
    item.bib_data.mms_id,
    item.holding_data.holding_id,
    item.item_data.pid,
    library="MAIN",
    circ_desk="DEFAULT",
    auto_print_slip=True,
)

`client.bibs.loans`¶

AlmaClientBibLoansNS ¶

AlmaClientBibLoansNS(client: _AlmaExecutable)

Bases: BaseNamespace

Namespace for bib loans, exposed at client.bibs.loans.

Loans reached from the bibliographic side – by record or by item – which is the route to take when you know what was borrowed but not who has it. To act on a loan (renewing it, changing its due date) use client.users.loans, which is where the write operations live.

get_loans `async` Alma: Loan By Item information ¶

get_loans(
    mms_id: str,
    holding_id: str,
    item_id: str,
    limit: int = ...,
    offset: int = ...,
    order_by: Literal[
        "loan_date",
        "due_date",
        "barcode",
        "title",
        "author",
        "return_date",
    ] = ...,
    direction: Literal["asc", "desc"] = ...,
    loan_status: Literal["Active", "Complete"] = ...,
    *,
    model: type[_ModelT],
) -> _ModelT

get_loans(
    mms_id: str,
    holding_id: str,
    item_id: str,
    limit: int = ...,
    offset: int = ...,
    order_by: Literal[
        "loan_date",
        "due_date",
        "barcode",
        "title",
        "author",
        "return_date",
    ] = ...,
    direction: Literal["asc", "desc"] = ...,
    loan_status: Literal["Active", "Complete"] = ...,
    *,
    model: None = ...,
) -> RESP_TYPE

Retrieves loans for a specific item.

create_loan `async` Alma: Create user loan ¶

create_loan(
    mms_id: str,
    holding_id: str,
    item_id: str,
    user_id: str,
    circ_desk: str,
    library: str,
    request_id: str | None = ...,
    *,
    model: type[_ModelT],
) -> _ModelT

create_loan(
    mms_id: str,
    holding_id: str,
    item_id: str,
    user_id: str,
    circ_desk: str,
    library: str,
    request_id: str | None = ...,
    *,
    model: None = ...,
) -> RESP_TYPE

Creates a loan for a specific copy of an item.

get_loan `async` Alma: Retrieve Item Loan information ¶

get_loan(
    mms_id: str,
    holding_id: str,
    item_id: str,
    loan_id: str,
    *,
    model: type[_ModelT],
) -> _ModelT

get_loan(
    mms_id: str,
    holding_id: str,
    item_id: str,
    loan_id: str,
    *,
    model: None = ...,
) -> RESP_TYPE

Get the details of a specific loan on a specific copy of an item.

renew_loan `async` Alma: Action on a loan ¶

renew_loan(
    mms_id: str,
    holding_id: str,
    item_id: str,
    loan_id: str,
    *,
    model: type[_ModelT],
) -> _ModelT

renew_loan(
    mms_id: str,
    holding_id: str,
    item_id: str,
    loan_id: str,
    *,
    model: None = ...,
) -> RESP_TYPE

Renew a loan on a specific copy of an item.

change_loan_due_date `async` Alma: Change loan due date ¶

change_loan_due_date(
    mms_id: str,
    holding_id: str,
    item_id: str,
    loan_id: str,
    due_date: str,
    *,
    model: type[_ModelT],
) -> _ModelT

change_loan_due_date(
    mms_id: str,
    holding_id: str,
    item_id: str,
    loan_id: str,
    due_date: str,
    *,
    model: None = ...,
) -> RESP_TYPE

Changes the due date of a loan on a specific copy of an item.

get_bib_loans `async` Alma: Retrieve Bib Loan information ¶

get_bib_loans(
    mms_id: str,
    limit: int = ...,
    offset: int = ...,
    order_by: Literal[
        "loan_date",
        "due_date",
        "barcode",
        "title",
        "author",
        "return_date",
    ] = ...,
    direction: Literal["asc", "desc"] = ...,
    loan_status: Literal["Active", "Complete"] = ...,
    *,
    model: type[_ModelT],
) -> _ModelT

get_bib_loans(
    mms_id: str,
    limit: int = ...,
    offset: int = ...,
    order_by: Literal[
        "loan_date",
        "due_date",
        "barcode",
        "title",
        "author",
        "return_date",
    ] = ...,
    direction: Literal["asc", "desc"] = ...,
    loan_status: Literal["Active", "Complete"] = ...,
    *,
    model: None = ...,
) -> RESP_TYPE

List every loan across all items on a bibliographic record.

The record-level counterpart to get_loans, which narrows to a single item.

Parameters:

Name	Type	Description	Default
`mms_id`	`str`	The MMS ID of the bibliographic record.	required
`limit`	`int`	Maximum number of loans to return in this page.	`100`
`offset`	`int`	Index of the first loan to return, for paging.	`0`
`order_by`	`Literal['loan_date', 'due_date', 'barcode', 'title', 'author', 'return_date']`	Field to sort by.	`'due_date'`
`direction`	`Literal['asc', 'desc']`	Sort direction.	`'asc'`
`loan_status`	`Literal['Active', 'Complete']`	`"Active"` for loans still out, `"Complete"` for returned ones.	`'Active'`
`model`	`Any`	Optional Pydantic model class to validate the response into.	`None`

Returns:

Type	Description
`Any`	A page of loans across the record's items, with `total_record_count`
`Any`	giving the full result size.

Raises:

Type	Description
`MMSIdNotFoundError`	If no record has that MMS ID.

Examples:

loans = await client.bibs.loans.get_bib_loans(
    "99123456789012345", loan_status="Active"
)
for loan in loans.item_loan:
    print(loan.item_barcode, loan.user_id, loan.due_date)

get_bib_loan `async` Alma: Retrieve Bib Loan information for a Bib id and Loan id ¶

get_bib_loan(
    mms_id: str, loan_id: str, *, model: type[_ModelT]
) -> _ModelT

get_bib_loan(
    mms_id: str, loan_id: str, *, model: None = ...
) -> RESP_TYPE

Retrieve a single loan on a bibliographic record.

Parameters:

Name	Type	Description	Default
`mms_id`	`str`	The MMS ID of the bibliographic record.	required
`loan_id`	`str`	The loan identifier.	required
`model`	`Any`	Optional Pydantic model class to validate the response into.	`None`

Returns:

Type	Description
`Any`	The loan record.

Raises:

Type	Description
`MMSIdNotFoundError`	If no record has that MMS ID.
`LoanNotFoundError`	If the record has no loan with that ID.

Examples:

loan = await client.bibs.loans.get_bib_loan("99123456789012345", "987654321")

`client.bibs.requests`¶

AlmaClientBibRequestsNS ¶

AlmaClientBibRequestsNS(client: _AlmaExecutable)

Bases: BaseNamespace

Namespace for bib requests, exposed at client.bibs.requests.

Requests reached from the bibliographic side. Alma splits these across two levels and this namespace mirrors that split, which is the main thing to get right here:

Item level – get_requests, get_request, create_request, update_request, cancel_request all take an MMS ID, holding ID and item PID, and act on requests against one physical copy.
Record level – the *_for_bib methods take only an MMS ID and act on title level requests, where Alma has not yet picked a copy.

client.users.requests covers the same requests from the borrower's side, and is where to start when you know the user rather than the record.

get_requests_for_item `class-attribute` `instance-attribute` ¶

get_requests_for_item = get_requests

Alias for get_requests.

get_requests `async` Alma: Retrieve User Requests per Item ¶

get_requests(
    mms_id: str,
    holding_id: str,
    item_id: str,
    request_type: Literal[
        "all_types", "HOLD", "DIGITIZATION", "BOOKING"
    ] = ...,
    status: Literal["active", "history"] = ...,
    *,
    model: type[_ModelT],
) -> _ModelT

get_requests(
    mms_id: str,
    holding_id: str,
    item_id: str,
    request_type: Literal[
        "all_types", "HOLD", "DIGITIZATION", "BOOKING"
    ] = ...,
    status: Literal["active", "history"] = ...,
    *,
    model: None = ...,
) -> RESP_TYPE

List the requests on a single item.

Also callable as client.bibs.requests.get_requests_for_item(...). For title level requests on the record as a whole, use get_requests_for_bib.

Parameters:

Name	Type	Description	Default
`mms_id`	`str`	The MMS ID of the bibliographic record.	required
`holding_id`	`str`	The holding ID the item belongs to.	required
`item_id`	`str`	The item PID.	required
`request_type`	`Literal['all_types', 'HOLD', 'DIGITIZATION', 'BOOKING']`	Restrict to one kind of request, or `"all_types"` for every kind.	`'all_types'`
`status`	`Literal['active', 'history']`	`"active"` for outstanding requests, `"history"` for completed and cancelled ones.	`'active'`
`model`	`Any`	Optional Pydantic model class to validate the response into.	`None`

Returns:

Type	Description
`Any`	The item's requests, with `total_record_count` giving the result size.

Raises:

Type	Description
`MMSIdNotFoundError`	If no record has that MMS ID.
`APIClientError`	If the holding or item does not exist.

Examples:

reqs = await client.bibs.requests.get_requests(
    "99123456789012345", "22123456780001234", "23123456770001234"
)

get_requests_for_bib `async` Alma: Retrieve User Requests per Bib ¶

get_requests_for_bib(
    mms_id: str,
    request_type: Literal[
        "all_types", "HOLD", "DIGITIZATION", "BOOKING"
    ] = ...,
    status: Literal["active", "history"] = ...,
    *,
    model: type[_ModelT],
) -> _ModelT

get_requests_for_bib(
    mms_id: str,
    request_type: Literal[
        "all_types", "HOLD", "DIGITIZATION", "BOOKING"
    ] = ...,
    status: Literal["active", "history"] = ...,
    *,
    model: None = ...,
) -> RESP_TYPE

List the title level requests on a bibliographic record.

Returns requests placed against the record as a whole, where Alma has not yet assigned a specific copy. For requests on one item, use get_requests.

Parameters:

Name	Type	Description	Default
`mms_id`	`str`	The MMS ID of the bibliographic record.	required
`request_type`	`Literal['all_types', 'HOLD', 'DIGITIZATION', 'BOOKING']`	Restrict to one kind of request, or `"all_types"` for every kind.	`'all_types'`
`status`	`Literal['active', 'history']`	`"active"` for outstanding requests, `"history"` for completed and cancelled ones.	`'active'`
`model`	`Any`	Optional Pydantic model class to validate the response into.	`None`

Returns:

Type	Description
`Any`	The record's title level requests.

Raises:

Type	Description
`MMSIdNotFoundError`	If no record has that MMS ID.

Examples:

reqs = await client.bibs.requests.get_requests_for_bib(
    "99123456789012345", request_type="HOLD"
)

get_request_for_bib `async` Alma: Retrieve User Title Request ¶

get_request_for_bib(
    mms_id: str, request_id: str, *, model: type[_ModelT]
) -> _ModelT

get_request_for_bib(
    mms_id: str, request_id: str, *, model: None = ...
) -> RESP_TYPE

Retrieve a single title level request on a bibliographic record.

Parameters:

Name	Type	Description	Default
`mms_id`	`str`	The MMS ID of the bibliographic record.	required
`request_id`	`str`	The request identifier.	required
`model`	`Any`	Optional Pydantic model class to validate the response into.	`None`

Returns:

Type	Description
`Any`	The request record.

Raises:

Type	Description
`MMSIdNotFoundError`	If no record has that MMS ID.
`APIClientError`	If the record has no request with that ID.

Examples:

req = await client.bibs.requests.get_request_for_bib(
    "99123456789012345", "987654321"
)

update_request_for_bib `async` Alma: Update Title Request ¶

update_request_for_bib(
    mms_id: str,
    request_id: str,
    request: Request,
    *,
    model: type[_ModelT],
) -> _ModelT

update_request_for_bib(
    mms_id: str,
    request_id: str,
    request: Request,
    *,
    model: None = ...,
) -> RESP_TYPE

Update a title level request on a bibliographic record.

Alma replaces the whole request, so fetch it with get_request_for_bib and modify that rather than sending a partial body.

Parameters:

Name	Type	Description	Default
`mms_id`	`str`	The MMS ID of the bibliographic record.	required
`request_id`	`str`	The request identifier.	required
`request`	`Request`	The full, modified request record.	required
`model`	`Any`	Optional Pydantic model class to validate the response into.	`None`

Returns:

Type	Description
`Any`	The updated request record.

Raises:

Type	Description
`MMSIdNotFoundError`	If no record has that MMS ID.
`APIClientError`	If the request does not exist, or a field that cannot be changed was modified.

Examples:

req = await client.bibs.requests.get_request_for_bib(
    "99123456789012345", "987654321"
)
req.pickup_location_library = "SCIENCE"
await client.bibs.requests.update_request_for_bib(
    "99123456789012345", "987654321", req
)

process_request_for_bib `async` Alma: Action on a request - Title ¶

process_request_for_bib(
    mms_id: str,
    request_id: str,
    op: str = ...,
    *,
    release_item: bool = ...,
    model: type[_ModelT],
) -> _ModelT

process_request_for_bib(
    mms_id: str,
    request_id: str,
    op: str = ...,
    *,
    release_item: bool = ...,
    model: None = ...,
) -> RESP_TYPE

Advance a title level request through its workflow.

Moves the request to the next step in Alma's fulfilment workflow – the API equivalent of processing it at a desk.

Being a POST, this call is not replayed if the response is lost in transit. See Rate limiting.

Parameters:

Name	Type	Description	Default
`mms_id`	`str`	The MMS ID of the bibliographic record.	required
`request_id`	`str`	The request identifier.	required
`op`	`str`	The operation to perform. `"next_step"` advances the request.	`'next_step'`
`release_item`	`bool`	Whether to release the item assigned to the request back into circulation as part of the operation.	`False`
`model`	`Any`	Optional Pydantic model class to validate the response into.	`None`

Returns:

Type	Description
`Any`	The request record in its new state.

Raises:

Type	Description
`MMSIdNotFoundError`	If no record has that MMS ID.
`APIClientError`	If the request does not exist, or is not in a state that can be advanced.

Examples:

req = await client.bibs.requests.process_request_for_bib(
    "99123456789012345", "987654321", op="next_step"
)

get_request `async` Alma: Retrieve User Item Request ¶

get_request(
    mms_id: str,
    holding_id: str,
    item_id: str,
    request_id: str,
    *,
    model: type[_ModelT],
) -> _ModelT

get_request(
    mms_id: str,
    holding_id: str,
    item_id: str,
    request_id: str,
    *,
    model: None = ...,
) -> RESP_TYPE

Retrieve a single request on an item.

Parameters:

Name	Type	Description	Default
`mms_id`	`str`	The MMS ID of the bibliographic record.	required
`holding_id`	`str`	The holding ID the item belongs to.	required
`item_id`	`str`	The item PID.	required
`request_id`	`str`	The request identifier.	required
`model`	`Any`	Optional Pydantic model class to validate the response into.	`None`

Returns:

Type	Description
`Any`	The request record.

Raises:

Type	Description
`MMSIdNotFoundError`	If no record has that MMS ID.
`APIClientError`	If the holding, item or request does not exist.

Examples:

req = await client.bibs.requests.get_request(
    "99123456789012345",
    "22123456780001234",
    "23123456770001234",
    "987654321",
)

cancel_request `async` Alma: Cancel Request ¶

cancel_request(
    mms_id: str,
    holding_id: str,
    item_id: str,
    request_id: str,
    reason: str,
    *,
    notify_user: bool,
    note: str | None = None,
) -> None

Cancel a request on an item.

Parameters:

Name	Type	Description	Default
`mms_id`	`str`	The MMS ID of the bibliographic record.	required
`holding_id`	`str`	The holding ID the item belongs to.	required
`item_id`	`str`	The item PID.	required
`request_id`	`str`	The request identifier.	required
`reason`	`str`	Cancellation reason. Must be a code from the `RequestCancellationReasons` code table – fetch the valid values with `client.config.code_tables.get_code_table()`.	required
`notify_user`	`bool`	Whether Alma should notify the requester.	required
`note`	`str \| None`	Free-text note included in the notification.	`None`

Returns:

Type	Description
`None`	`None`. Alma returns an empty body on success.

Raises:

Type	Description
`MMSIdNotFoundError`	If no record has that MMS ID.
`APIClientError`	If the request does not exist, is already fulfilled, or the reason code is not valid.

Examples:

await client.bibs.requests.cancel_request(
    "99123456789012345",
    "22123456780001234",
    "23123456770001234",
    "987654321",
    reason="CannotBeFulfilled",
    notify_user=True,
)

create_request `async` Alma: Create request for an Item ¶

create_request(
    mms_id: str,
    holding_id: str,
    item_id: str,
    user_id: str,
    request: Request,
    user_id_type: str = ...,
    *,
    allow_same_request: bool = ...,
    model: type[_ModelT],
) -> _ModelT

create_request(
    mms_id: str,
    holding_id: str,
    item_id: str,
    user_id: str,
    request: Request,
    user_id_type: str = ...,
    *,
    allow_same_request: bool = ...,
    model: None = ...,
) -> RESP_TYPE

Place a request on a specific item.

Pins the request to one physical copy. To let Alma choose a copy, place a title level request with client.users.requests.create_request() instead.

Being a POST, this call is not replayed if the response is lost in transit – a retry could place a duplicate request. See Rate limiting.

Parameters:

Name	Type	Description	Default
`mms_id`	`str`	The MMS ID of the bibliographic record.	required
`holding_id`	`str`	The holding ID the item belongs to.	required
`item_id`	`str`	The item PID.	required
`user_id`	`str`	The identifier of the user the request is for.	required
`request`	`Request`	The request to create. Requires at least `request_type` and, for holds, a `pickup_location_type` and `pickup_location_library`.	required
`user_id_type`	`str`	Which kind of identifier `user_id` is.	`'all_unique'`
`allow_same_request`	`bool`	Whether to permit a second request when the user already has one on this title.	`False`
`model`	`Any`	Optional Pydantic model class to validate the response into.	`None`

Returns:

Type	Description
`Any`	The newly created request record, including its `request_id`.

Raises:

Type	Description
`RequestFailedError`	If Alma rejected the request (code `401873`).
`NoItemsCanFulfillRequestError`	If the item cannot satisfy it.
`ParallelRequestError`	If the user already has a request on another copy and `allow_same_request` is False.
`MMSIdNotFoundError`	If no record has that MMS ID.
`UserNotFoundError`	If no user matches the identifier.

Examples:

req = await client.bibs.requests.create_request(
    "99123456789012345",
    "22123456780001234",
    "23123456770001234",
    "12345678",
    {
        "request_type": "HOLD",
        "pickup_location_type": "LIBRARY",
        "pickup_location_library": "MAIN",
    },
)

update_request `async` Alma: Update Item Request ¶

update_request(
    mms_id: str,
    holding_id: str,
    item_id: str,
    request_id: str,
    request: Request,
    *,
    model: type[_ModelT],
) -> _ModelT

update_request(
    mms_id: str,
    holding_id: str,
    item_id: str,
    request_id: str,
    request: Request,
    *,
    model: None = ...,
) -> RESP_TYPE

Update a request on an item.

Alma replaces the whole request, so fetch it with get_request and modify that rather than sending a partial body.

Parameters:

Name	Type	Description	Default
`mms_id`	`str`	The MMS ID of the bibliographic record.	required
`holding_id`	`str`	The holding ID the item belongs to.	required
`item_id`	`str`	The item PID.	required
`request_id`	`str`	The request identifier.	required
`request`	`Request`	The full, modified request record.	required
`model`	`Any`	Optional Pydantic model class to validate the response into.	`None`

Returns:

Type	Description
`Any`	The updated request record.

Raises:

Type	Description
`MMSIdNotFoundError`	If no record has that MMS ID.
`APIClientError`	If the request does not exist, or a field that cannot be changed was modified.

Examples:

req = await client.bibs.requests.get_request(
    "99123456789012345", "22123456780001234", "23123456770001234", "987654321"
)
req.pickup_location_library = "SCIENCE"
await client.bibs.requests.update_request(
    "99123456789012345",
    "22123456780001234",
    "23123456770001234",
    "987654321",
    req,
)

`client.bibs.representations`¶

Alma Digital representations on a record, and the files under each one. Files are not uploaded through this API – create_file registers a file already staged in the institution's S3 upload folder.

AlmaClientBibRepresentationsNS ¶

AlmaClientBibRepresentationsNS(client: _AlmaExecutable)

Bases: BaseNamespace

Namespace for digital representations, exposed at client.bibs.representations.

Representations and their files live under a bibliographic record, so every method here wants an MMS ID. Start with get_representations to find the representation IDs a record carries.

The file methods – get_files, get_file, create_file, update_file, delete_file – are supported for non-remote representations only. A remote representation points at an external repository and has no files in Alma.

Everything here returns a Box and accepts model=, except the two delete methods, which return None.

get_representations `async` Alma: Retrieve Representations ¶

get_representations(
    mms_id: str,
    *,
    originating_record_id: str | None = ...,
    limit: int = ...,
    offset: int = ...,
    use_updated_terminology: bool = ...,
    model: type[_ModelT],
) -> _ModelT

get_representations(
    mms_id: str,
    *,
    originating_record_id: str | None = ...,
    limit: int = ...,
    offset: int = ...,
    use_updated_terminology: bool = ...,
    model: None = ...,
) -> RESP_TYPE

List the digital representations on a bibliographic record.

Parameters:

Name	Type	Description	Default
`mms_id`	`str`	The MMS ID of the bibliographic record.	required
`originating_record_id`	`str \| None`	Restrict the result to the representation whose object has this ID in the remote repository. Only meaningful for remote representations.	`None`
`limit`	`int`	Maximum number of representations to return in this page. Note the default here is 10, not 100; Alma caps it at 100.	`10`
`offset`	`int`	Index of the first representation to return, for paging.	`0`
`use_updated_terminology`	`bool`	Report the usage type of the institution's main representation as `PRIMARY` rather than the older `DERIVATIVE_COPY`.	`False`
`model`	`Any`	Optional Pydantic model class to validate the response into.	`None`

Returns:

Type	Description
`Any`	A page of representations, with `total_record_count` giving the full
`Any`	result size.

Raises:

Type	Description
`MMSIdNotFoundError`	If no record has that MMS ID.

Examples:

reps = await client.bibs.representations.get_representations(
    "99123456789012345", limit=100
)
for rep in reps.representation:
    print(rep.id, rep.label, rep.usage_type.value)

get_representation `async` Alma: Retrieve Representation Details ¶

get_representation(
    mms_id: str,
    rep_id: str,
    *,
    use_updated_terminology: bool = ...,
    model: type[_ModelT],
) -> _ModelT

get_representation(
    mms_id: str,
    rep_id: str,
    *,
    use_updated_terminology: bool = ...,
    model: None = ...,
) -> RESP_TYPE

Retrieve one digital representation.

Works for both remote and non-remote representations.

Parameters:

Name	Type	Description	Default
`mms_id`	`str`	The MMS ID of the bibliographic record.	required
`rep_id`	`str`	The representation ID.	required
`use_updated_terminology`	`bool`	Report the usage type of the institution's main representation as `PRIMARY` rather than the older `DERIVATIVE_COPY`.	`False`
`model`	`Any`	Optional Pydantic model class to validate the response into.	`None`

Returns:

Type	Description
`Any`	The representation record.

Raises:

Type	Description
`MMSIdNotFoundError`	If no record has that MMS ID.
`APIClientError`	If the representation does not exist.

Examples:

rep = await client.bibs.representations.get_representation(
    "99123456789012345", "12345678900001234"
)
print(rep.label, rep.library.value)

create_representation `async` Alma: Create Representation ¶

create_representation(
    mms_id: str,
    representation: Body,
    *,
    generate_label: bool = ...,
    model: type[_ModelT],
) -> _ModelT

create_representation(
    mms_id: str,
    representation: Body,
    *,
    generate_label: bool = ...,
    model: None = ...,
) -> RESP_TYPE

Create a digital representation on a bibliographic record.

Being a POST, this call is not replayed if the response is lost in transit – a retry could create a duplicate representation. See Rate limiting.

Parameters:

Name	Type	Description	Default
`mms_id`	`str`	The MMS ID of the bibliographic record.	required
`representation`	`Body`	The representation to create. `library` and `usage_type` are mandatory; `is_remote` defaults to `false`. Accepts a mapping or any object implementing `dump`/`model_dump`.	required
`generate_label`	`bool`	Whether Alma should build the representation's label from its entity type and bibliographic fields.	`False`
`model`	`Any`	Optional Pydantic model class to validate the response into.	`None`

Returns:

Type	Description
`Any`	The newly created representation, including its assigned ID.

Raises:

Type	Description
`MMSIdNotFoundError`	If no record has that MMS ID.
`BibNotInCollectionError`	If the bib record is not assigned to a collection, which Alma Digital requires.
`APIClientError`	If the library or usage type is not valid for this institution.

Examples:

rep = await client.bibs.representations.create_representation(
    "99123456789012345",
    {
        "library": {"value": "MAIN"},
        "usage_type": {"value": "DERIVATIVE_COPY"},
        "label": "Digitised copy",
    },
)

update_representation `async` Alma: Update Representation ¶

update_representation(
    mms_id: str,
    rep_id: str,
    representation: Body,
    *,
    generate_label: bool = ...,
    handle_bib: Literal["retain", "suppress"] = ...,
    model: type[_ModelT],
) -> _ModelT

update_representation(
    mms_id: str,
    rep_id: str,
    representation: Body,
    *,
    generate_label: bool = ...,
    handle_bib: Literal["retain", "suppress"] = ...,
    model: None = ...,
) -> RESP_TYPE

Update a digital representation.

Alma replaces the whole representation, so fetch it with get_representation and modify that rather than sending a partial body.

Parameters:

Name	Type	Description	Default
`mms_id`	`str`	The MMS ID of the bibliographic record.	required
`rep_id`	`str`	The representation ID.	required
`representation`	`Body`	The full, modified representation. Accepts a mapping or any object implementing `dump`/`model_dump`.	required
`generate_label`	`bool`	Whether Alma should rebuild the representation's label from its entity type and bibliographic fields.	`False`
`handle_bib`	`Literal['retain', 'suppress']`	What to do with the bib record if this update leaves it without an active representation – `"retain"` or `"suppress"`.	`'retain'`
`model`	`Any`	Optional Pydantic model class to validate the response into.	`None`

Returns:

Type	Description
`Any`	The updated representation.

Raises:

Type	Description
`MMSIdNotFoundError`	If no record has that MMS ID.
`APIClientError`	If the representation does not exist, or a code in the body is not valid for this institution.

Examples:

rep = await client.bibs.representations.get_representation(
    "99123456789012345", "12345678900001234"
)
rep.public_note = "Access restricted to reading room"
await client.bibs.representations.update_representation(
    "99123456789012345", "12345678900001234", rep
)

delete_representation `async` Alma: Delete Representation ¶

delete_representation(
    mms_id: str,
    rep_id: str,
    *,
    override: bool = False,
    handle_bib: Literal[
        "retain", "suppress", "delete"
    ] = "retain",
) -> None

Delete a digital representation.

Deleting a representation deletes its files with it. handle_bib defaults to "retain", the conservative choice – deleting the bib record removes everything else attached to it too.

Parameters:

Name	Type	Description	Default
`mms_id`	`str`	The MMS ID of the bibliographic record.	required
`rep_id`	`str`	The representation ID.	required
`override`	`bool`	Delete even when Alma raises warnings. Defaults to `False` so the shortest call cannot silently discard content.	`False`
`handle_bib`	`Literal['retain', 'suppress', 'delete']`	What to do with the bib record if this was its last representation – `"retain"`, `"suppress"` or `"delete"`.	`'retain'`

Returns:

Type	Description
`None`	`None`. Alma returns an empty body on success.

Raises:

Type	Description
`MMSIdNotFoundError`	If no record has that MMS ID.
`APIClientError`	If the representation does not exist.

Examples:

await client.bibs.representations.delete_representation(
    "99123456789012345", "12345678900001234"
)

get_files `async` Alma: Retrieve Representation Files' Details ¶

get_files(
    mms_id: str,
    rep_id: str,
    *,
    expand_url: bool = ...,
    model: type[_ModelT],
) -> _ModelT

get_files(
    mms_id: str,
    rep_id: str,
    *,
    expand_url: bool = ...,
    model: None = ...,
) -> RESP_TYPE

List the files on a digital representation.

Supported for non-remote representations only.

Parameters:

Name	Type	Description	Default
`mms_id`	`str`	The MMS ID of the bibliographic record.	required
`rep_id`	`str`	The representation ID.	required
`expand_url`	`bool`	Send `expand=url`, which makes Alma populate each file's `url` field with a signed download link. Off by default – the links are short-lived and cost Alma work to mint.	`False`
`model`	`Any`	Optional Pydantic model class to validate the response into.	`None`

Returns:

Type	Description
`Any`	The representation's files, with `total_record_count` giving the full
`Any`	result size.

Raises:

Type	Description
`MMSIdNotFoundError`	If no record has that MMS ID.
`APIClientError`	If the representation does not exist or is remote.

Examples:

files = await client.bibs.representations.get_files(
    "99123456789012345", "12345678900001234", expand_url=True
)
for f in files.representation_file:
    print(f.pid, f.label, f.url)

get_file `async` Alma: Retrieve Representation File Details ¶

get_file(
    mms_id: str,
    rep_id: str,
    file_id: str,
    *,
    expand_url: bool = ...,
    model: type[_ModelT],
) -> _ModelT

get_file(
    mms_id: str,
    rep_id: str,
    file_id: str,
    *,
    expand_url: bool = ...,
    model: None = ...,
) -> RESP_TYPE

Retrieve one file from a digital representation.

Supported for non-remote representations only.

Parameters:

Name	Type	Description	Default
`mms_id`	`str`	The MMS ID of the bibliographic record.	required
`rep_id`	`str`	The representation ID.	required
`file_id`	`str`	The file ID.	required
`expand_url`	`bool`	Send `expand=url`, which makes Alma populate the file's `url` field with a signed download link.	`False`
`model`	`Any`	Optional Pydantic model class to validate the response into.	`None`

Returns:

Type	Description
`Any`	The file record.

Raises:

Type	Description
`MMSIdNotFoundError`	If no record has that MMS ID.
`APIClientError`	If the representation or file does not exist.

Examples:

f = await client.bibs.representations.get_file(
    "99123456789012345", "12345678900001234", "23456789000001234"
)
print(f.label, f.path)

create_file `async` Alma: Create Representation File ¶

create_file(
    mms_id: str,
    rep_id: str,
    file: Body,
    *,
    timeout: float | tuple[float, float] | None = ...,
    model: type[_ModelT],
) -> _ModelT

create_file(
    mms_id: str,
    rep_id: str,
    file: Body,
    *,
    timeout: float | tuple[float, float] | None = ...,
    model: None = ...,
) -> RESP_TYPE

Register a file on a digital representation.

This does not upload bytes. The file must already have been placed in the institution's S3 upload folder, and path in the body is its location there, starting with the institution code – for example 01UNI_INST/upload/scratch/1234/file.png. See Alma Digital.

Alma moves the file from the upload folder to permanent storage as part of this call, so it can take many seconds on a large file. The session's read timeout is 90 seconds; pass timeout= to raise it for this call.

Being a POST, this call is not replayed if the response is lost in transit – a retry could register a duplicate file. See Rate limiting.

Parameters:

Name	Type	Description	Default
`mms_id`	`str`	The MMS ID of the bibliographic record.	required
`rep_id`	`str`	The representation ID.	required
`file`	`Body`	The file to register. `path` is mandatory. Accepts a mapping or any object implementing `dump`/`model_dump`.	required
`timeout`	`float \| tuple[float, float] \| None`	Override the transport timeout for this call, in seconds. Either a single value or a `(connect, read)` pair.	`None`
`model`	`Any`	Optional Pydantic model class to validate the response into.	`None`

Returns:

Type	Description
`Any`	The newly registered file, including its assigned PID and its final
`Any`	storage path.

Raises:

Type	Description
`MMSIdNotFoundError`	If no record has that MMS ID.
`APIClientError`	If the representation does not exist or is remote, or the path does not resolve to a file in the upload folder.

Examples:

f = await client.bibs.representations.create_file(
    "99123456789012345",
    "12345678900001234",
    {"label": "Page 1", "path": "01UNI_INST/upload/scratch/1234/page1.jpg"},
    timeout=120,
)

update_file `async` Alma: Update Representation File ¶

update_file(
    mms_id: str,
    rep_id: str,
    file_id: str,
    file: Body,
    *,
    model: type[_ModelT],
) -> _ModelT

update_file(
    mms_id: str,
    rep_id: str,
    file_id: str,
    file: Body,
    *,
    model: None = ...,
) -> RESP_TYPE

Update a file on a digital representation.

Alma replaces the whole file record, so fetch it with get_file and modify that rather than sending a partial body. Only the metadata is updatable – to replace the bytes, register a new file and delete this one.

Parameters:

Name	Type	Description	Default
`mms_id`	`str`	The MMS ID of the bibliographic record.	required
`rep_id`	`str`	The representation ID.	required
`file_id`	`str`	The file ID.	required
`file`	`Body`	The full, modified file record. Accepts a mapping or any object implementing `dump`/`model_dump`.	required
`model`	`Any`	Optional Pydantic model class to validate the response into.	`None`

Returns:

Type	Description
`Any`	The updated file record.

Raises:

Type	Description
`MMSIdNotFoundError`	If no record has that MMS ID.
`APIClientError`	If the representation or file does not exist.

Examples:

await client.bibs.representations.update_file(
    "99123456789012345",
    "12345678900001234",
    "23456789000001234",
    {"label": "Title page"},
)

delete_file `async` Alma: Delete Representation File ¶

delete_file(
    mms_id: str,
    rep_id: str,
    file_id: str,
    *,
    handle_representation: Literal[
        "retain", "delete"
    ] = "retain",
    handle_bib: Literal[
        "retain", "suppress", "delete"
    ] = "retain",
) -> None

Delete a file from a digital representation.

Both dispositions default to "retain", the conservative choice: a representation left with no files, and a bib left with no representations, stay where they are unless asked otherwise.

Parameters:

Name	Type	Description	Default
`mms_id`	`str`	The MMS ID of the bibliographic record.	required
`rep_id`	`str`	The representation ID.	required
`file_id`	`str`	The file ID.	required
`handle_representation`	`Literal['retain', 'delete']`	What to do with the representation if this was its last file – `"retain"` or `"delete"`.	`'retain'`
`handle_bib`	`Literal['retain', 'suppress', 'delete']`	What to do with the bib record if the representation is deleted and was its last one – `"retain"`, `"suppress"` or `"delete"`. Only reachable when `handle_representation` is `"delete"`.	`'retain'`

Returns:

Type	Description
`None`	`None`. Alma returns an empty body on success.

Raises:

Type	Description
`MMSIdNotFoundError`	If no record has that MMS ID.
`APIClientError`	If the representation or file does not exist.

Examples:

await client.bibs.representations.delete_file(
    "99123456789012345", "12345678900001234", "23456789000001234"
)

Bibs, holdings and items¶

client.bibs¶

AlmaClientBibNS ¶

get_item async Alma: Retrieve Item and label printing information ¶

get_item_by_pid async Alma: Retrieve Item and label printing information ¶

create_item async Alma: Create Item ¶

update_item async Alma: Update Item information ¶

withdraw_item async Alma: Withdraw Item ¶

get_items async Alma: Retrieve Items list ¶

get_portfolios async Alma: Retrieve Portfolios list ¶

get_holding async Alma: Retrieve Holdings Record ¶

update_holding async Alma: Update Holdings Record ¶

create_holding async Alma: Create holding record ¶

delete_holding async Alma: Delete Holdings Record ¶

get_holdings async Alma: Retrieve Holdings list ¶

create_bib async Alma: Create record ¶

get_bib async Alma: Retrieve Bib ¶

update_bib async Alma: Update Bib Record ¶

delete_bib async Alma: Delete Bib Record ¶

scan_in async Alma: Scan-in operation on item. ¶

client.bibs.loans¶

AlmaClientBibLoansNS ¶

get_loans async Alma: Loan By Item information ¶

create_loan async Alma: Create user loan ¶

get_loan async Alma: Retrieve Item Loan information ¶

renew_loan async Alma: Action on a loan ¶

change_loan_due_date async Alma: Change loan due date ¶

get_bib_loans async Alma: Retrieve Bib Loan information ¶

get_bib_loan async Alma: Retrieve Bib Loan information for a Bib id and Loan id ¶

client.bibs.requests¶

AlmaClientBibRequestsNS ¶

get_requests_for_item class-attribute instance-attribute ¶

get_requests async Alma: Retrieve User Requests per Item ¶

get_requests_for_bib async Alma: Retrieve User Requests per Bib ¶

get_request_for_bib async Alma: Retrieve User Title Request ¶

update_request_for_bib async Alma: Update Title Request ¶

process_request_for_bib async Alma: Action on a request - Title ¶

get_request async Alma: Retrieve User Item Request ¶

cancel_request async Alma: Cancel Request ¶

create_request async Alma: Create request for an Item ¶

update_request async Alma: Update Item Request ¶

client.bibs.representations¶

AlmaClientBibRepresentationsNS ¶

get_representations async Alma: Retrieve Representations ¶

get_representation async Alma: Retrieve Representation Details ¶

create_representation async Alma: Create Representation ¶

update_representation async Alma: Update Representation ¶

delete_representation async Alma: Delete Representation ¶

get_files async Alma: Retrieve Representation Files' Details ¶

get_file async Alma: Retrieve Representation File Details ¶

create_file async Alma: Create Representation File ¶

update_file async Alma: Update Representation File ¶

delete_file async Alma: Delete Representation File ¶

`client.bibs`¶

get_item `async` Alma: Retrieve Item and label printing information ¶

get_item_by_pid `async` Alma: Retrieve Item and label printing information ¶

create_item `async` Alma: Create Item ¶

update_item `async` Alma: Update Item information ¶

withdraw_item `async` Alma: Withdraw Item ¶

get_items `async` Alma: Retrieve Items list ¶

get_portfolios `async` Alma: Retrieve Portfolios list ¶

get_holding `async` Alma: Retrieve Holdings Record ¶

update_holding `async` Alma: Update Holdings Record ¶

create_holding `async` Alma: Create holding record ¶

delete_holding `async` Alma: Delete Holdings Record ¶

get_holdings `async` Alma: Retrieve Holdings list ¶

create_bib `async` Alma: Create record ¶

get_bib `async` Alma: Retrieve Bib ¶

update_bib `async` Alma: Update Bib Record ¶

delete_bib `async` Alma: Delete Bib Record ¶

scan_in `async` Alma: Scan-in operation on item. ¶

`client.bibs.loans`¶

get_loans `async` Alma: Loan By Item information ¶

create_loan `async` Alma: Create user loan ¶

get_loan `async` Alma: Retrieve Item Loan information ¶

renew_loan `async` Alma: Action on a loan ¶

change_loan_due_date `async` Alma: Change loan due date ¶

get_bib_loans `async` Alma: Retrieve Bib Loan information ¶

get_bib_loan `async` Alma: Retrieve Bib Loan information for a Bib id and Loan id ¶

`client.bibs.requests`¶

get_requests_for_item `class-attribute` `instance-attribute` ¶

get_requests `async` Alma: Retrieve User Requests per Item ¶

get_requests_for_bib `async` Alma: Retrieve User Requests per Bib ¶

get_request_for_bib `async` Alma: Retrieve User Title Request ¶

update_request_for_bib `async` Alma: Update Title Request ¶

process_request_for_bib `async` Alma: Action on a request - Title ¶

get_request `async` Alma: Retrieve User Item Request ¶

cancel_request `async` Alma: Cancel Request ¶

create_request `async` Alma: Create request for an Item ¶

update_request `async` Alma: Update Item Request ¶

`client.bibs.representations`¶

get_representations `async` Alma: Retrieve Representations ¶

get_representation `async` Alma: Retrieve Representation Details ¶

create_representation `async` Alma: Create Representation ¶

update_representation `async` Alma: Update Representation ¶

delete_representation `async` Alma: Delete Representation ¶

get_files `async` Alma: Retrieve Representation Files' Details ¶

get_file `async` Alma: Retrieve Representation File Details ¶

create_file `async` Alma: Create Representation File ¶

update_file `async` Alma: Update Representation File ¶

delete_file `async` Alma: Delete Representation File ¶