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 entry point group (Default: None). fetchers_entry_point_group – The fetchers entry point group (Default: None).
Returns:	PIDStore state application.

init_config(app)[source]¶: Initialize configuration.

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:	invenio_pidstore.errors.PIDInvalidAction – If the PID was previously deleted. invenio_pidstore.errors.PIDObjectAlreadyAssigned – If the PID was previously assigned with a different type/uuid.
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:	invenio_pidstore.errors.PIDInvalidAction – If the PID is not registered or is not already redirecting to another PID. invenio_pidstore.errors.PIDDoesNotExistError – If PID is not found.
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 = '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 = 'N'¶: PID has not yet been registered with the service provider.

REDIRECTED = 'M'¶: PID has been redirected to another persistent identifier.

REGISTERED = 'R'¶: PID has been registered with the service provider.

RESERVED = 'K'¶: PID reserved in the service provider but not yet fully registered.

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 = '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:	pid_type – Persistent identifier type. (Default: configured `invenio_pidstore.providers.base.BaseProvider.pid_type`) pid_value – Persistent identifier value. kwargs – See `invenio_pidstore.providers.base.BaseProvider()` required initialization properties.
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 = '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: (we will use control_number as value of PIDSTORE_RECID_FIELD for the simplicity of the documentation.)

#. 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.

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.

API Docs¶

Extension¶

Models¶

Resolver¶

Providers¶

Minters¶

Fetchers¶

Exceptions¶

CLI¶

Invenio-PIDStore

Navigation

Related Topics