API Docs

Extension

Invenio module that stores and registers persistent identifiers.

class invenio_pidstore.ext.InvenioPIDStore(app=None, minters_entry_point_group='invenio_pidstore.minters', fetchers_entry_point_group='invenio_pidstore.fetchers')[source]

Invenio-PIDStore extension.

Extension initialization.

Parameters:
  • minters_entry_point_group – The entrypoint for minters. (Default: invenio_pidstore.minters).
  • fetchers_entry_point_group – The entrypoint for fetchers. (Default: invenio_pidstore.fetchers).
init_app(app, minters_entry_point_group=None, fetchers_entry_point_group=None)[source]

Flask application initialization.

Initialize:

  • The CLI commands.

  • Initialize the logger (Default: app.debug).

  • Initialize the default admin object link endpoint.

    (Default: {“rec”: “recordmetadata.details_view”} if invenio-records is installed, otherwise {}).

  • Register the pid_exists template filter.

  • Initialize extension state.

Parameters:
  • app – The Flask application
  • minters_entry_point_group – The minters entrtypoint group (Default: None).
  • fetchers_entry_point_group – The fetchers entrtypoint group (Default: None). :returns: PIDStore state application.
invenio_pidstore.ext.pid_exists(value, pidtype=None)[source]

Check if a persistent identifier exists.

Parameters:
  • value – The PID value.
  • pidtype – The pid value (Default: None).
Returns:

True if the PID exists.

Models

Persistent identifier store and registration.

class invenio_pidstore.models.PersistentIdentifier(**kwargs)[source]

Store and register persistent identifiers.

Assumptions:
  • Persistent identifiers can be represented as a string of max 255 chars.
  • An object has many persistent identifiers.
  • A persistent identifier has one and only one object.

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

assign(object_type, object_uuid, overwrite=False)[source]

Assign this persistent identifier to a given object.

Note, the persistent identifier must first have been reserved. Also, if an existing object is already assigned to the pid, it will raise an exception unless overwrite=True.

Parameters:
  • object_type – The object type is a string that identify its type.
  • object_uuid – The object UUID.
  • overwrite – Force PID overwrites in case was previously assigned.
Raises:
Returns:

True if the PID is successfully assigned.

classmethod create(pid_type, pid_value, pid_provider=None, status=<PIDStatus.NEW: 'N'>, object_type=None, object_uuid=None)[source]

Create a new persistent identifier with specific type and value.

Parameters:
  • pid_type – Persistent identifier type.
  • pid_value – Persistent identifier value.
  • pid_provider – Persistent identifier provider. (default: None).
  • status – Current PID status. (Default: invenio_pidstore.models.PIDStatus.NEW)
  • object_type – The object type is a string that identify its type. (default: None).
  • object_uuid – The object UUID. (default: None).
Returns:

A invenio_pidstore.models.PersistentIdentifier instance.

delete()[source]

Delete the persistent identifier.

If the persistent identifier haven’t been registered yet, it is removed from the database. Otherwise, it’s marked as invenio_pidstore.models.PIDStatus.DELETED. :returns: True if the PID is successfully removed.

classmethod get(pid_type, pid_value, pid_provider=None)[source]

Get persistent identifier.

Parameters:
  • pid_type – Persistent identifier type.
  • pid_value – Persistent identifier value.
  • pid_provider – Persistent identifier provider. (default: None).
Raises:

invenio_pidstore.errors.PIDDoesNotExistError if no PID is found.

Returns:

A invenio_pidstore.models.PersistentIdentifier instance.

get_assigned_object(object_type=None)[source]

Return the current assigned object UUID.

Parameters:object_type – If it’s specified, returns only if the PID object_type is the same, otherwise returns None. (default: None).
Returns:The object UUID.
classmethod get_by_object(pid_type, object_type, object_uuid)[source]

Get a persistent identifier for a given object.

Parameters:
  • pid_type – Persistent identifier type.
  • object_type – The object type is a string that identify its type.
  • object_uuid – The object UUID.
Raises:

invenio_pidstore.errors.PIDDoesNotExistError – If no PID is found.

Returns:

A invenio_pidstore.models.PersistentIdentifier instance.

get_redirect()[source]

Get redirected persistent identifier.

Returns:The invenio_pidstore.models.PersistentIdentifier instance.
has_object()[source]

Determine if this PID has an assigned object.

Returns:True if the PID has a object assigned.
id

Id of persistent identifier entry.

is_deleted()[source]

Return true if the persistent identifier has been deleted.

Returns:A boolean value.
is_new()[source]

Return true if the PIDhas not yet been registered or reserved.

Returns:A boolean value.
is_redirected()[source]

Return true if the persistent identifier has been registered.

is_registered()[source]

Return true if the persistent identifier has been registered.

Returns:A invenio_pidstore.models.PIDStatus status.
is_reserved()[source]

Return true if the PID has not yet been reserved.

Returns:A boolean value.
object_type

Object Type - e.g. rec for record.

object_uuid

Object ID - e.g. a record id.

pid_provider

Persistent Identifier Provider

pid_type

Persistent Identifier Schema.

pid_value

Persistent Identifier.

redirect(pid)[source]

Redirect persistent identifier to another persistent identifier.

Parameters:

pid – The invenio_pidstore.models.PersistentIdentifier where redirect the PID.

Raises:
Returns:

True if the PID is successfully redirect.

register()[source]

Register the persistent identifier with the provider.

Raises:invenio_pidstore.errors.PIDInvalidAction – If the PID is not already registered or is deleted or is a redirection to another PID.
Returns:True if the PID is successfully register.
reserve()[source]

Reserve the persistent identifier.

Note, the reserve method may be called multiple times, even if it was already reserved.

Raises:invenio_pidstore.errors.PIDInvalidAction if the PID is not new or is not already reserved a PID.
Returns:True if the PID is successfully reserved.
status

Status of persistent identifier, e.g. registered, reserved, deleted.

sync_status(status)[source]

Synchronize persistent identifier status.

Used when the provider uses an external service, which might have been modified outside of our system.

Parameters:status – The new status to set.
Returns:True if the PID is successfully sync.
unassign()[source]

Unassign the registered object.

Note: Only registered PIDs can be redirected so we set it back to registered.

Returns:True if the PID is successfully unassigned.
class invenio_pidstore.models.PIDStatus(value)[source]

Constants for possible status of any given PID.

Hack.

DELETED = <PIDStatus.DELETED: 'D'>

PID has been deleted/inactivated with the service provider.

This should happen very rarely, and must be kept track of, as the PID should not be reused for something else.

NEW = <PIDStatus.NEW: 'N'>

PID has not yet been registered with the service provider.

REDIRECTED = <PIDStatus.REDIRECTED: 'M'>

PID has been redirected to another persistent identifier.

REGISTERED = <PIDStatus.REGISTERED: 'R'>

PID has been registered with the service provider.

RESERVED = <PIDStatus.RESERVED: 'K'>

PID reserved in the service provider but not yet fully registered.

title

Return human readable title.

class invenio_pidstore.models.RecordIdentifier(**kwargs)[source]

Sequence generator for integer record identifiers.

The sole purpose of this model is to generate integer record identifiers in sequence using the underlying database’s auto increment features in a transaction friendly manner. The feature is primarily provided to support legacy Invenio instances to continue their current record identifier scheme. For new instances we strong encourage to not use auto incrementing record identifiers, but instead use e.g. UUIDs as record identifiers.

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

classmethod insert(val)[source]

Insert a record identifier.

Parameters:val – The recid column value to insert.
classmethod max()[source]

Get max record identifier.

classmethod next()[source]

Return next available record identifier.

class invenio_pidstore.models.Redirect(**kwargs)[source]

Redirect for a persistent identifier.

You can redirect a PID to another one.

E.g.

pid1 = PersistentIdentifier.get(pid_type="recid", pid_value="1")
pid2 = PersistentIdentifier.get(pid_type="recid", pid_value="2")
pid1.redirect(pid=pid2)
assert pid2.pid_value == pid.get_redirect().pid_value

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

id

Id of redirect entry.

pid

Relationship to persistent identifier.

pid_id

Persistent identifier.

Resolver

Internal resolver for persistent identifiers.

class invenio_pidstore.resolver.Resolver(pid_type=None, object_type=None, getter=None)[source]

Persistent identifier resolver.

Helper class for retrieving an internal object for a given persistent identifier.

Initialize resolver.

Parameters:
  • pid_type – Persistent identifier type.
  • object_type – Object type.
  • getter – Callable that will take an object id for the given object type and retrieve the internal object.
resolve(pid_value)[source]

Resolve a persistent identifier to an internal object.

Parameters:pid_value – Persistent identifier.
Returns:A tuple containing (pid, object).

Providers

Implementations of different PID providers.

Module storing implementations of PID providers.

class invenio_pidstore.providers.base.BaseProvider(pid)[source]

Abstract class for persistent identifier provider classes.

Initialize provider using persistent identifier.

Parameters:pid – A invenio_pidstore.models.PersistentIdentifier instance.
classmethod create(pid_type=None, pid_value=None, object_type=None, object_uuid=None, status=None, **kwargs)[source]

Create a new instance for the given type and pid.

Parameters:
  • pid_type – Persistent identifier type. (Default: None).
  • pid_value – Persistent identifier value. (Default: None).
  • status – Current PID status. (Default: invenio_pidstore.models.PIDStatus.NEW)
  • object_type – The object type is a string that identify its type. (Default: None).
  • object_uuid – The object UUID. (Default: None).
Returns:

A invenio_pidstore.providers.base.BaseProvider instance.

default_status = <PIDStatus.NEW: 'N'>

Default status for newly created PIDs by this provider.

delete()[source]

Delete a persistent identifier.

See: invenio_pidstore.models.PersistentIdentifier.delete().

classmethod get(pid_value, pid_type=None, **kwargs)[source]

Get a persistent identifier for this provider.

Parameters:
Returns:

A invenio_pidstore.providers.base.BaseProvider instance.

pid_provider = None

Persistent identifier provider name.

pid_type = None

Default persistent identifier type.

register()[source]

Register a persistent identifier.

See: invenio_pidstore.models.PersistentIdentifier.register().

reserve()[source]

Reserve a persistent identifier.

This might or might not be useful depending on the service of the provider.

See: invenio_pidstore.models.PersistentIdentifier.reserve().

sync_status()[source]

Synchronize PIDstatus with remote service provider.

update()[source]

Update information about the persistent identifier.

Record ID provider.

class invenio_pidstore.providers.recordid.RecordIdProvider(pid)[source]

Record identifier provider.

Initialize provider using persistent identifier.

Parameters:pid – A invenio_pidstore.models.PersistentIdentifier instance.
classmethod create(object_type=None, object_uuid=None, **kwargs)[source]

Create a new record identifier.

Note: if the object_type and object_uuid values are passed, then the PID status will be automatically setted to invenio_pidstore.models.PIDStatus.REGISTERED.

Parameters:
  • object_type – The object type. (Default: None.)
  • object_uuid – The object identifier. (Default: None).
  • kwargs – You specify the pid_value.
default_status = <PIDStatus.RESERVED: 'K'>

Record IDs are by default registered immediately.

Default: invenio_pidstore.models.PIDStatus.RESERVED

pid_provider = None

Provider name.

The provider name is not recorded in the PID since the provider does not provide any additional features besides creation of record ids.

pid_type = 'recid'

Type of persistent identifier.

Minters

Persistent identifier minters.

invenio_pidstore.minters.recid_minter(record_uuid, data)[source]

Mint record identifiers.

This is a minter specific for records. With the help of invenio_pidstore.providers.recordid.RecordIdProvider, it creates the PID instance with rec as predefined object_type.

Procedure followed:

#. If a control_number field is already there, a AssertionError exception is raised.

#. The provider is initialized with the help of invenio_pidstore.providers.recordid.RecordIdProvider. It’s called with default value ‘rec’ for object_type and record_uuid variable for object_uuid.

  1. The new id_value is stored inside data as control_number field.
Parameters:
  • record_uuid – The record UUID.
  • data – The record metadata.
Returns:

A fresh invenio_pidstore.models.PersistentIdentifier instance.

Fetchers

Persistent identifier fetchers.

A proper fetcher is defined as a function that return a invenio_pidstore.fetchers.FetchedPID instance.

E.g.

def my_fetcher(record_uuid, data):
    return FetchedPID(
        provider=MyRecordIdProvider,
        pid_type=MyRecordIdProvider.pid_type,
        pid_value=extract_pid_value(data),
    )

To see more about providers see invenio_pidstore.providers.

class invenio_pidstore.fetchers.FetchedPID(provider, pid_type, pid_value)

A pid fetcher.

pid_type

Alias for field number 1

pid_value

Alias for field number 2

provider

Alias for field number 0

invenio_pidstore.fetchers.recid_fetcher(record_uuid, data)[source]

Fetch a record’s identifiers.

Parameters:
  • record_uuid – The record UUID.
  • data – The record metadata.
Returns:

A invenio_pidstore.fetchers.FetchedPID instance.

Exceptions

Errors for persistent identifiers.

exception invenio_pidstore.errors.PIDAlreadyExists(pid_type, pid_value, *args, **kwargs)[source]

Persistent identifier already exists error.

Initialize exception.

exception invenio_pidstore.errors.PIDDeletedError(pid, record, *args, **kwargs)[source]

Persistent identifier is deleted.

Initialize exception.

exception invenio_pidstore.errors.PIDDoesNotExistError(pid_type, pid_value, *args, **kwargs)[source]

PID does not exists error.

Initialize exception.

exception invenio_pidstore.errors.PIDInvalidAction[source]

Invalid operation on persistent identifier in current state.

exception invenio_pidstore.errors.PIDMissingObjectError(pid, *args, **kwargs)[source]

Persistent identifier has no object.

Initialize exception.

exception invenio_pidstore.errors.PIDObjectAlreadyAssigned[source]

Persistent identifier is already assigned to another object.

exception invenio_pidstore.errors.PIDRedirectedError(pid, dest_pid, *args, **kwargs)[source]

Persistent identifier is redirected to another pid.

Initialize exception.

exception invenio_pidstore.errors.PIDUnregistered(pid, *args, **kwargs)[source]

Persistent identifier has not been registered.

Initialize exception.

exception invenio_pidstore.errors.PIDValueError(pid_type, pid_value, *args, **kwargs)[source]

Base class for value errors.

Initialize exception.

exception invenio_pidstore.errors.PersistentIdentifierError[source]

Base class for PIDStore errors.

exception invenio_pidstore.errors.ResolverError(pid, *args, **kwargs)[source]

Persistent identifier does not exists.

Initialize exception.

CLI

Detailed usage documentation is available by running inveniomanage pid --help.

Click command-line interface for PIDStore management.

invenio_pidstore.cli.process_status(ctx, param, value)[source]

Return status value.