metadata module¶

This module was designed to facilitate the management of metadata for various types of content that can be deposited on Zenodo. It defines several classes that encapsulate different content types, such as datasets, publications, images, posters, presentations, videos, software, lessons, and physical objects. These classes provide a structured way to create and manage metadata for Zenodo depositions. The module includes methods for creating instances of these metadata classes and rendering them with specified replacements for placeholders.

Examples

from zen.metadata import Dataset, Creators, Placeholder

# Creating a dataset metadata instance
meta = Dataset(
    title='My Dataset',
    description='Description of the dataset',
    creators=[Creators.new(name='Doe, John')],
    access_right='Open Access',
    license='cc-by',
    embargo_date='2024-01-01'
)

# Creating a templated metadata
meta = Dataset(
    title='My Dataset',
    description='Description of the {the_type} dataset',
    creators=Placeholder('the_authors'),
    access_right='Open Access',
    license='cc-by',
    embargo_date='2024-01-01'
)

# Show placeholders
print(meta.placeholders)
#> {'the_type', 'the_authors'}

# Render metadata
replacements = {
    'the_authors': [{'name': 'Doe, John'}],
    'the_type': 'random'
}
rendered_metadata = meta.render(replacements)

# Creating Publication metadata from a JSON file
meta = Dataset.from_file('examples/metadata.json')

class zen.metadata.AccessRight(data: Dict[str, Any], default_license: str)¶

Bases: _MetaBase

Represents the access rights of a Zenodo deposition.

This helper class class provides methods to define the access rights of a Zenodo deposition.

Parameters:

data (Dict[str,Any]) – The dictionary representing the deposition metadata.
default_license (str) – The default license to be used when access is set to ‘open’.

access_rights = ['open', 'embargoed', 'restricted', 'closed']¶

property data: str¶

Get the access right data.

If the ‘access_right’ is not present in the data, it defaults to ‘open’ with the default license.

set(value: str) → None¶

Set the access right to the specified value.

Parameters:: value (str) – The desired access right value.
Raises:: ValueError – If the specified value is not a valid access right.

set_closed() → None¶: Set the access right to ‘closed’.

set_embargoed(license: str, embargo_date: str | None = None) → None¶

Set the access right to ‘embargoed’ and specify a license and, optionally, an embargo date.

Parameters:

license (str) – The license for the deposition.
embargo_date (str, optional) – The date when the deposition will become publicly accessible.

set_open(license: str) → None¶

Set the access right to ‘open’ and specify a license.

Parameters:: license (str) – The license for the deposition.

set_restricted(access_conditions: str) → None¶

Set the access right to ‘restricted’ and specify access conditions.

Parameters:: access_conditions (str) – Access conditions for the deposition.

class zen.metadata.Communities(data: Dict[str, Any])¶

Bases: _MetaBaseListObject

Represents a list of communities associated with a Zenodo deposition.

This helper class provides methods for managing and manipulating community identifiers.

Parameters:: data (Dict[str,Any]) – The dictionary representing the deposition metadata.

add(identifier: str) → Communities¶

Add a community identifier entry to the list.

Parameters:: identifier (str) – The community identifier to add.
Returns:: The updated Communities instance.
Return type:: Communities

clear() → Communities¶

Clears the community identifier list.

Empty community identifier list.

Returns:: An empty Communities object.
Return type:: Communities

classmethod new(identifier: str) → Dict[str, str]¶

Create a new community entry.

Parameters:: identifier (str) – The community identifier to create.
Returns:: A dictionary representing the community entry.
Return type:: Dict[str,str]

class zen.metadata.Contributors(data: Dict[str, Any])¶

Bases: _MetaBaseListObject

Represents a list of contributors associated with a Zenodo deposition.

This helper class provides methods for managing and manipulating contributor information, including name, type, affiliation, ORCID, and GND.

Parameters:: data (Dict[str,Any]) – The dictionary representing the deposition metadata.

add(type: str, name: str, affiliation: str | None = None, orcid: str | None = None, gnd: str | None = None) → Contributors¶

Add a new contributor entry to the list.

Parameters:

type (str) – The type of contributor (e.g., ‘ContactPerson’, ‘DataCollector’, etc.).
name (str) – The name of the contributor.
affiliation (Optional[str]=None) – The affiliation of the contributor.
orcid (Optional[str]=None) – The ORCID identifier of the contributor.
gnd (Optional[str]=None) – The GND identifier of the contributor.

Returns:

The updated Contributors instance.

Return type:

Contributors

Raises:

ValueError – If the provided contributor type is not supported.

clear() → Contributors¶

Clears the contributors list.

Empty contributors list.

Returns:: An empty Contributors object.
Return type:: Contributors

contributor_types = ['ContactPerson', 'DataCollector', 'DataCurator', 'DataManager,Distributor', 'Editor', 'HostingInstitution', 'Producer', 'ProjectLeader', 'ProjectManager', 'ProjectMember', 'RegistrationAgency', 'RegistrationAuthority', 'RelatedPerson', 'Researcher', 'ResearchGroup', 'RightsHolder,Supervisor', 'Sponsor', 'WorkPackageLeader', 'Other']¶

classmethod new(name: str, type: str, affiliation: str | None = None, orcid: str | None = None, gnd: str | None = None) → Dict[str, str]¶

Create a new contributor entry.

Parameters:

name (str) – The name of the contributor.
type (str) – The type of contributor (e.g., ‘ContactPerson’, ‘DataCollector’, etc.).
affiliation (Optional[str]) – The affiliation of the contributor.
orcid (Optional[str]) – The ORCID identifier of the contributor.
gnd (Optional[str]) – The GND identifier of the contributor.

Returns:

A dictionary representing the contributor entry.

Return type:

Dict[str,str]

Raises:

ValueError – If the provided contributor type is not supported.

class zen.metadata.Creators(data: Dict[str, Any])¶

Bases: _MetaBaseListObject

Represents a list of creators associated with a Zenodo deposition.

This helper class class provides methods for managing a list of creators, which are individuals or entities who have contributed to a Zenodo deposition. Creators can be associated with names, affiliations, ORCID iDs, and GND identifiers.

Parameters:: data (Dict[str,Any]) – The dictionary representing the deposition metadata.

Examples

Create a new Zenodo deposition with default metadata:

>>> from zen import Zenodo
>>> zen = Zenodo(url=Zenodo.sandbox_url, token='your_api_token')
>>> dep = zen.depositions.create()
>>> dep.metadata

Add new creators

>>> from zen.metadata import Creators
>>> dep.metadata.creators.add('Doe, John', 'Zenodo')
>>> dep.metadata.creators.add('Mae, Anna', 'Zenodo')
>>> # This will duplicate the first author
>>> dep.metadata.creators.add('Doe, John', 'Zenodo')

Alternative way to set creators

>>> dep.metadata.creators = [
...     Creators.new('Doe, John', 'Zenodo'),
...     Creators.new('Mae, Anna', 'Zenodo')
... ]

This will produce the same result as above.

Discard the deposition example.

>>> dep.discard()

add(name: str, affiliation: str | None = None, orcid: str | None = None, gnd: str | None = None) → Creators¶

Adds a new creator to the creators list.

Adds a new creator to the list with the provided information and returns the updated Creators object.

Parameters:

name (str) – The name of the creator.
affiliation (Optional[str]) – The affiliation of the creator. Default is None.
orcid (Optional[str]) – The ORCID identifier of the creator. Default is None.
gnd (Optional[str]) – The GND identifier of the creator. Default is None.

Returns:

An updated Creators object with the new creator added to the list.

Return type:

Creators

clear() → Creators¶

Clears the creators list.

Empty creators list.

Returns:: An empty Creators object.
Return type:: Creators

classmethod new(name: str, affiliation: str | None = None, orcid: str | None = None, gnd: str | None = None) → Dict[str, str]¶

Returns a new creator dictionary.

Creates a new creator with the provided information and returns the creator’s data as a dictionary.

Parameters:

name (str) – The name of the creator.
affiliation (Optional[str]=None) – The affiliation of the creator. Default is None.
orcid (Optional[str]=None) – The ORCID identifier of the creator. Default is None.
gnd (Optional[str]=None) – The GND identifier of the creator. Default is None.

Returns:

A dictionary containing the creator’s data.

Return type:

Dict[str,str]

Bases: Metadata

Represents metadata for a Dataset deposition on Zenodo.

Create a Dataset metadata instance (upload_type=’dataset’).

Parameters:

title (Optional[Union[str,Placeholder]]=None) – The title of the deposition.
description (Optional[Union[str,Placeholder]]=None) – Description of the deposition (allows HTML).
creators (Optional[Union[List[Dict[str,str]],Placeholder]]=None) – List of deposition creators.
access_right (Optional[Union[str,Placeholder]]=None) – Access rights for the deposition.
license (Optional[Union[str,Placeholder]]=None) – License information for the deposition.
embargo_date (Optional[Union[str,Placeholder]]=None) – Date when the deposition will become publicly accessible.
access_conditions (Optional[Union[str,Placeholder]]=None) – Custom access conditions.
publication_date (Optional[Union[str,Placeholder]]=None) – Date of publication.
**kwargs – Additional custom metadata parameters that can be set when creating an instance of this metadata class. Users can provide any extra metadata fields they need, but it is recommended to consult the Zenodo API reference for a complete list of allowed metadata parameters. Consult the Zenodo API reference for a comprehensive list of supported metadata fields and their descriptions.

property access_right: AccessRight¶: Get the access right for the dataset (The default is ‘cc-zero’).

classmethod from_file(file: str) → Self¶

Create a Dataset metadata instance from a JSON file.

Parameters:

file (str) – The path to a JSON file containing metadata.

Returns:

An instance of the metadata class populated with the data from the JSON file.

Return type:

Dataset

Raises:

TypeError – If the JSON file has an invalid format.
ValueError – If the upload_type in the metadata is not supported.

class zen.metadata.Dates(data: Dict[str, Any])¶

Bases: _MetaBaseListObject

Represents a list of dates associated with a Zenodo deposition.

This helper class provides methods for managing and manipulating dates, such as collection dates, valid dates, and withdrawal dates.

Parameters:: data (Dict[str,Any]) – The dictionary representing the deposition metadata.

add(type: str, start: str | None = None, end: str | None = None, description: str | None = None) → Dates¶

Add a new date entry to the list.

Parameters:

type (str) – The type of the date entry (e.g., ‘Collected’, ‘Valid’, ‘Withdrawn’).
start (Optional[str]=None) – The start date in ISO 8601 format (e.g., ‘YYYY-MM-DD’).
end (Optional[str]=None) – The end date in ISO 8601 format (e.g., ‘YYYY-MM-DD’).
description (Optional[str]=None) – A description of the date entry.

Returns:

The updated Dates instance.

Return type:

Dates

Raises:

ValueError – If the provided type is not a supported date type or if date formats are invalid.

clear() → Dates¶

Clears the date list.

Empty date list.

Returns:: An empty Dates object.
Return type:: Dates

date_types = ['Collected', 'Valid', 'Withdrawn']¶

classmethod new(type: str, start: str | None = None, end: str | None = None, description: str | None = None) → Dict[str, str]¶

Create a new date entry.

Parameters:

type (str) – The type of the date entry (e.g., ‘Collected’, ‘Valid’, ‘Withdrawn’).
start (Optional[str]=None) – The start date in ISO 8601 format (e.g., ‘YYYY-MM-DD’).
end (Optional[str]=None) – The end date in ISO 8601 format (e.g., ‘YYYY-MM-DD’).
description (Optional[str]=None) – A description of the date entry.

Returns:

A dictionary representing the date entry.

Return type:

Dict[str,str]

Raises:

ValueError – If the provided type is not a supported date type or if date formats are invalid.

class zen.metadata.Grants(data: Dict[str, Any])¶

Bases: _MetaBaseListObject

Represents a list of grants associated with a Zenodo deposition.

This helper class provides methods for managing and manipulating grant identifiers.

Parameters:: data (Dict[str,Any]) – The dictionary representing the deposition metadata.

add(id: str) → Grants¶

Add a grant identifier entry to the list

Parameters:: id (str) – The grant identifier to add.
Returns:: The updated Grants instance.
Return type:: Grants

clear() → Grants¶

Clears the grant identifier list.

Empty grant identifier list.

Returns:: An empty Grants object.
Return type:: Grants

classmethod new(id: str) → Dict[str, str]¶

Create a new grant entry.

Parameters:: id (str) – The grant identifier to create.
Returns:: A dictionary representing the grant entry.
Return type:: Dict[str,str]

Bases: Metadata

Represents metadata for an Image deposition on Zenodo.

Create an Image metadata instance (upload_type=’image’).

Parameters:

image_type (str) – Type of the image. One of Image.image_types.
title (Optional[Union[str,Placeholder]]=None) – The title of the deposition.
description (Optional[Union[str,Placeholder]]=None) – Description of the deposition (allows HTML).
creators (Optional[Union[List[Dict[str,str]],Placeholder]]=None) – List of deposition creators.
access_right (Optional[Union[str,Placeholder]]=None) – Access rights for the deposition.
license (Optional[Union[str,Placeholder]]=None) – License information for the deposition.
embargo_date (Optional[Union[str,Placeholder]]=None) – Date when the deposition will become publicly accessible.
access_conditions (Optional[Union[str,Placeholder]]=None) – Custom access conditions.
publication_date (Optional[Union[str,Placeholder]]=None) – Date of publication.
**kwargs – Additional custom metadata parameters that can be set when creating an instance of this metadata class. Users can provide any extra metadata fields they need, but it is recommended to consult the Zenodo API reference for a complete list of allowed metadata parameters. Consult the Zenodo API reference for a comprehensive list of supported metadata fields and their descriptions.

classmethod from_file(file: str) → Self¶

Create an Image metadata instance from a JSON file

Parameters:

file (str) – The path to a JSON file containing metadata.

Returns:

An instance of the metadata class populated with the data from the JSON file.

Return type:

Image

Raises:

TypeError – If the JSON file has an invalid format.
ValueError – If the upload_type in the metadata is not supported.

image_types = ['figure', 'plot', 'drawing', 'diagram', 'photo', 'other']¶

class zen.metadata.Keywords(data: Dict[str, Any])¶

Bases: _MetaBaseListString

Represents a list of keywords associated with a Zenodo deposition.

This helper class provides methods for managing and manipulating keywords.

Parameters:: data (Dict[str,Any]) – The dictionary representing the deposition metadata.

add(keyword: str) → Keywords¶

Add a keyword to the list

Parameters:: keyword (str) – The keyword to add.
Returns:: The updated Keywords instance.
Return type:: Keywords
Raises:: ValueError – If the provided keyword is not a string.

classmethod new(keyword: str) → str¶

Create a new keyword

Parameters:: keyword (str) – The keyword to create.
Returns:: The keyword.
Return type:: str
Raises:: ValueError – If the provided keyword is not a string.

Bases: Metadata

Represents metadata for a Lesson deposition on Zenodo.

Create a Lesson metadata instance (upload_type=’lesson’).

Parameters:

title (Optional[Union[str,Placeholder]]=None) – The title of the deposition.
description (Optional[Union[str,Placeholder]]=None) – Description of the deposition (allows HTML).
creators (Optional[Union[List[Dict[str,str]],Placeholder]]=None) – List of deposition creators.
access_right (Optional[Union[str,Placeholder]]=None) – Access rights for the deposition.
license (Optional[Union[str,Placeholder]]=None) – License information for the deposition.
embargo_date (Optional[Union[str,Placeholder]]=None) – Date when the deposition will become publicly accessible.
access_conditions (Optional[Union[str,Placeholder]]=None) – Custom access conditions.
publication_date (Optional[Union[str,Placeholder]]=None) – Date of publication.
**kwargs – Additional custom metadata parameters that can be set when creating an instance of this metadata class. Users can provide any extra metadata fields they need, but it is recommended to consult the Zenodo API reference for a complete list of allowed metadata parameters. Consult the Zenodo API reference for a comprehensive list of supported metadata fields and their descriptions.

classmethod from_file(file: str) → Self¶

Create a Lesson metadata instance from a JSON file.

Parameters:

file (str) – The path to a JSON file containing metadata.

Returns:

An instance of the metadata class populated with the data from the JSON file.

Return type:

Lesson

Raises:

TypeError – If the JSON file has an invalid format.
ValueError – If the upload_type in the metadata is not supported.

class zen.metadata.Locations(data: Dict[str, Any])¶

Bases: _MetaBaseListObject

Represents a list of locations associated with a Zenodo deposition.

This helper class provides methods for managing and manipulating location information, including place, latitude, longitude, and description.

Parameters:: data (Dict[str,Any]) – The dictionary representing the deposition metadata.

add(place: str, lat: float | None = None, lon: float | None = None, description: str | None = None) → Locations¶

Add a location entry to the list

Parameters:

place (str) – The location’s name or description.
lat (Optional[float]=None) – The latitude coordinate of the location.
lon (Optional[float]=None) – The longitude coordinate of the location.
description (Optional[str]=None) – A description of the location.

Returns:

The updated Locations instance.

Return type:

Locations

clear() → Locations¶

Clears the location list.

Empty location list.

Returns:: An empty Locations object.
Return type:: Locations

classmethod new(place: str, lat: float | None = None, lon: float | None = None, description: str | None = None) → Dict[str, str | float]¶

Create a new location entry.

Parameters:

place (str) – The location’s name or description.
lat (Optional[float]=None) – The latitude coordinate of the location.
lon (Optional[float]=None) – The longitude coordinate of the location.
description (Optional[str]=None) – A description of the location.

Returns:

A dictionary representing the location entry.

Return type:

Dict[str,Union[str,float]]

class zen.metadata.Metadata(data: Dict[str, Any] | None = None)¶

Bases: _MetaBaseObject

Represents a Zenodo deposition metadata.

Create a deposition metadata instance.

Parameters:: data (Optional[Dict[str,Any]]=None) – The deposition dictionary where the ‘metadata’ key entry belongs.

property access_conditions: str¶

Conditions under which users can access the deposition files.

Specify the conditions under which you grant users access to the files in your upload. User requesting access will be asked to justify how they fulfil the conditions. Based on the justification, you decide who to grant/deny access. You are not allowed to charge users for granting access to data hosted on Zenodo.

property access_right: AccessRight¶

The access rights of the deposition (required field).

Controlled vocabulary:

open: Open Access
embargoed: Embargoed Access
restricted: Restricted Access
closed: Closed Access

Defaults to open. Uses the helper class AccessRight.

property communities: Communities¶

List of communities associated with the deposition.

The owner of the community will be notified, and can either accept or reject your request.

Each array element is an object with the attributes:

identifier: Community identifier

Example: [{‘identifier’:’ecfunded’}]

Uses the helper class Communities.

property conference_acronym: str¶

Acronym of conference.

Example: “CHEP’13”

property conference_dates: str¶

Dates of conference.

Conference title or acronym must also be specified if this field is specified.

Example: ‘14-18 October 2013’

property conference_place: str¶

Place of conference in the format city, country.

Conference title or acronym must also be specified if this field is specified.

Example: ‘Amsterdam, The Netherlands’

property conference_session: str¶

Number of session within the conference.

Example: ‘VI’

property conference_session_part: str¶

Number of part within a session.

Example: ‘1’

property conference_title: str¶

Title of conference.

Example: ‘20th International Conference on Computing in High Energy and Nuclear Physics’.

property conference_url: str¶

URL of conference.

Example: ‘http://www.chep2013.org/’

property contributors: Contributors¶

The contributors of the deposition.

Lists all the contributors of the deposition (e.g. editors, data curators, etc.).

Each array element is an object with the attributes: * name: Name of creator in the format Family name, Given names * type: Contributor type. Controlled vocabulary (Please, see Contributors.contributor_types) * affiliation: Affiliation of creator (optional). * orcid: ORCID identifier of creator (optional). * gnd: GND identifier of creator (optional).

Example: [{‘name’:’Doe, John’, ‘affiliation’: ‘Zenodo’, ‘type’: ‘Editor’ }, …]

Uses the helper class Contributors

property creators: Creators¶

The creators/authors of the deposition (required field).

Each array element is an object with the attributes:

name: Name of creator in the format Family name, Given names.
affiliation: Affiliation of creator (optional).
orcid: ORCID identifier of creator (optional).
gnd: GND identifier of creator (optional).

Uses the helper class Creators.

property dates: Dates¶

List of dates associated with the deposition.

List of date intervals

start (ISO date Type: string): start date (*)
end (ISO date Type: string): end date (*)
type (Collected, Valid, Withdrawn): The interval’s type (required)
description (Type: string): The interval’s description (optional)

Note that you have to specify at least a start or end date. For an exact date, use the same value for both start and end.

Example: [{“start”: “2018-03-21”, “end”: “2018-03-25”, “type”: “Collected”,: “description”: “Specimen A5 collection period.”}]

property description: str¶: Abstract or description for deposition (allows HTML) (required field).

property embargo_date: str¶

Date of public availability of the deposition.

Date when the deposition will be made publicly available (required field if access_right is ‘embargoed’).

Defaults to current date.

classmethod from_file(file: str) → Metadata¶

Create a metadata instance from a JSON file.

Parameters:

file (str) – The path to a JSON file containing metadata.

Returns:

An instance of the metadata class populated with the data from the JSON file.

Return type:

Metadata

Raises:

TypeError – If the JSON file has an invalid format.
ValueError – If the upload_type in the metadata is not supported.

property grants¶

List of OpenAIRE-supported grants, which have funded the research for this deposition.

Each array element is an object with the attributes:

id: grant ID.

Example: [{‘id’:’283595’}] (European Commission grants only) or

funder DOI-prefixed: [{‘id’: ‘10.13039/501100000780::283595’}] (All grants, recommended)

Accepted funder DOI prefixes:

Australian Research Council: 10.13039/501100000923
Austrian Science Fund: 10.13039/501100002428
European Commission: 10.13039/501100000780
European Environment Agency: 10.13039/501100000806
Academy of Finland: 10.13039/501100002341
Agence Nationale de la Recherche: 10.13039/501100001665
Aligning Science Across Parkinson’s: 10.13039/100018231
Hrvatska Zaklada za Znanost: 10.13039/501100004488
Fundação para a Ciência e a Tecnologia: 10.13039/501100001871
Ministarstvo Prosvete, Nauke i Tehnološkog Razvoja: 10.13039/501100004564
Ministarstvo Znanosti, Obrazovanja i Sporta: 10.13039/501100006588
National Health and Medical Research Council: 10.13039/501100000925
National Institutes of Health: 10.13039/100000002
National Science Foundation: 10.13039/100000001
Nederlandse Organisatie voor Wetenschappelijk Onderzoek: 10.13039/501100003246
Research Councils: 10.13039/501100000690
UK Research and Innovation: 10.13039/100014013
Schweizerischer Nationalfonds zur Förderung der wissenschaftlichen Forschung: 10.13039/501100001711
Science Foundation Ireland: 10.13039/501100001602
Social Science Research Council: 10.13039/100001345
Türkiye Bilimsel ve Teknolojik Araştırma Kurumu: 10.13039/501100004410
Wellcome Trust: 10.13039/100004440

Uses the helper class Grants.

property image_type: str¶

Type of the deposition (required field).

Controlled vocabulary:

publication: Publication
poster: Poster
presentation: Presentation
dataset: Dataset
image: Image
video: Video/Audio
software: Software
lesson: Lesson
physicalobject: Physical object
other: Other

property imprint_isbn: str¶: ISBN of a book/report.

property imprint_place: str¶: Place of publication of a book/report/chapter in the format city, country.

property imprint_publisher: str¶: Publisher of a book/report/chapter.

property journal_issue: str¶: Journal issue, if deposition is a published article.

property journal_pages: str¶: Journal pages, if deposition is a published article.

property journal_title: str¶: Journal title, if deposition is a published article.

property journal_volume: str¶: Journal volume, if deposition is a published article.

property keywords: Keywords¶

The keywords associated with the deposition.

Example: [‘Keyword 1’, ‘Keyword 2’]

Uses the helper class Keywords

property language: str¶

The main language of the record.

Specify the main language of the record as ISO 639-2 or 639-3 code see Library of Congress ISO 639 codes list.

Example: eng

property license: str | None¶

The deposition license.

License of the data (required field if access_right is ‘open’ or ‘embargoed’). The selected license applies to all files in this deposition, but not to the metadata which is licensed under Creative Commons Zero.

You can find the available license IDs via Zenodo.licenses() method.

Defaults to ‘cc-zero’ for datasets and ‘cc-by’ for everything else.

property locations: Locations¶

List of locations associated with the deposition.

List of locations

lat (double): latitude
lon (double): longitude
place (Type: string): place’s name (required)
description (Type: string): place’s description (optional)

Example: [{“lat”: 34.02577, “lon”: -118.7804, “place”: “Los Angeles”},

{“place”: “Mt.Fuji, Japan”,: “description”: “Sample found 100ft from the foot of the mountain.”}]

Uses the helper class Locations

property method: str¶: The methodology employed for the study or research.

property notes: str¶: Additional notes (allows HTML).

property partof_pages: str¶: Pages numbers of book.

property partof_title: str¶: Title of book for chapters.

property placeholders: Set[str]¶: List of the placeholders in the metadata.

property prereserve_doi: bool¶

Reserve a Digital Object Identifier (DOI).

Set to true, to reserve a Digital Object Identifier (DOI). The DOI is automatically generated by our system and cannot be changed. Also, The DOI is not registered with DataCite until you publish your deposition, and thus cannot be used before then. Reserving a DOI is useful, if you need to include it in the files you upload, or if you need to provide a dataset DOI to your publisher but not yet publish your dataset. The response from the REST API will include the reserved DOI.

Defaults to True.

property publication_type: str¶

Type of the deposition (required field).

Controlled vocabulary:

publication: Publication
poster: Poster
presentation: Presentation
dataset: Dataset
image: Image
video: Video/Audio
software: Software
lesson: Lesson
physicalobject: Physical object
other: Other

property references: References¶

List of references.

Example: [“Doe J (2014). Title. Publisher. DOI”, “Smith J (2014). Title. Publisher. DOI”]

Uses the helper class References.

property related_identifiers: RelatedIdent¶

Persistent identifiers of related publications and datasets.

Supported identifiers include: DOI, Handle, ARK, PURL, ISSN, ISBN, PubMed ID, PubMed Central ID, ADS Bibliographic Code, arXiv, Life Science Identifiers (LSID), EAN-13, ISTC, URNs and URLs.

Each array element is an object with the attributes:

identifier: The persistent identifier
relation: Relationship. Controlled vocabulary (Please, see RelatedIdent.supported_identifiers).
resource_type: Type of the related resource (based on the ‘upload_type’, ‘publication_type’, and ‘image_type’ fields).

Example: [{‘relation’: ‘isSupplementTo’, ‘identifier’:’10.1234/foo’},

{‘relation’: ‘cites’, ‘identifier’:’https://doi.org/10.1234/bar’,: ‘resource_type’: ‘image-diagram’}].

Note the identifier type (e.g. DOI) is automatically detected, and used to validate and normalize the identifier into a standard form.

render(replacements: Dict[str, Any] | None = None) → Dict[str, Any]¶

Render the metadata by replacing placeholders with provided values.

This method is renders metadata with specific values by replacing placeholders with the values provided in the replacements dictionary. It ensures that all required placeholders have corresponding replacements and returns the updated metadata as a dictionary.

Parameters:: replacements (Optional[Dict[str,Any]]=None) – A dictionary of placeholder replacements. If not provided, an empty dictionary is used.
Raises:: ValueError – If any required placeholders are missing from the replacements dictionary.
Returns:: The rendered metadata with placeholders replaced by their corresponding values.
Return type:: Dict[str,Any]

property subjects: Subjects¶

The subjects associated with the deposition.

Specify subjects from a taxonomy or controlled vocabulary. Each term must be uniquely identified (e.g. a URL). For free form text, use the keywords field.

Each array element is an object with the attributes:

term: Term from taxonomy or controlled vocabulary.
identifier: Unique identifier for term.
scheme: Persistent identifier scheme for id (automatically detected).

Example: [{“term”: “Astronomy”, “identifier”: “http://id.loc.gov/authorities/subjects/sh85009003”,

“scheme”: “url”}]

Uses the helper class Subjects.

property thesis_supervisors: str¶

Supervisors of the thesis.

Same format as for creators.

Uses the helper class ThesisSupervisors

property thesis_university: str¶: Awarding university of thesis.

property title: str¶: Title of deposition (required field).

property upload_type: str¶

Type of the deposition (required field).

Controlled vocabulary:

publication: Publication
poster: Poster
presentation: Presentation
dataset: Dataset
image: Image
video: Video/Audio
software: Software
lesson: Lesson
physicalobject: Physical object
other: Other

upload_types = ['publication', 'poster', 'presentation', 'dataset', 'image', 'video', 'software', 'lesson', 'physicalobject', 'other']¶

property version: str¶

The version of the resource.

Any Type of string will be accepted, however the suggested format is a semantically versioned tag (see more details on semantic versioning at semver.org)

Example: ‘2.1.5’

Bases: Metadata

Represents metadata for Other deposition on Zenodo.

Create an Other metadata instance (upload_type=’other’).

Parameters:

title (Optional[Union[str,Placeholder]]=None) – The title of the deposition.
description (Optional[Union[str,Placeholder]]=None) – Description of the deposition (allows HTML).
creators (Optional[Union[List[Dict[str,str]],Placeholder]]=None) – List of deposition creators.
access_right (Optional[Union[str,Placeholder]]=None) – Access rights for the deposition.
license (Optional[Union[str,Placeholder]]=None) – License information for the deposition.
embargo_date (Optional[Union[str,Placeholder]]=None) – Date when the deposition will become publicly accessible.
access_conditions (Optional[Union[str,Placeholder]]=None) – Custom access conditions.
publication_date (Optional[Union[str,Placeholder]]=None) – Date of publication.
**kwargs – Additional custom metadata parameters that can be set when creating an instance of this metadata class. Users can provide any extra metadata fields they need, but it is recommended to consult the Zenodo API reference for a complete list of allowed metadata parameters. Consult the Zenodo API reference for a comprehensive list of supported metadata fields and their descriptions.

classmethod from_file(file: str) → Self¶

Create an Other metadata instance from a JSON file.

Parameters:

file (str) – The path to a JSON file containing metadata.

Returns:

An instance of the metadata class populated with the data from the JSON file.

Return type:

Other

Raises:

TypeError – If the JSON file has an invalid format.
ValueError – If the upload_type in the metadata is not supported.

Bases: Metadata

Represents metadata for a PhysicalObject deposition on Zenodo.

Create a PhysicalObject metadata instance (upload_type=’physicalobject’).

Parameters:

title (Optional[Union[str,Placeholder]]=None) – The title of the deposition.
description (Optional[Union[str,Placeholder]]=None) – Description of the deposition (allows HTML).
creators (Optional[Union[List[Dict[str,str]],Placeholder]]=None) – List of deposition creators.
access_right (Optional[Union[str,Placeholder]]=None) – Access rights for the deposition.
license (Optional[Union[str,Placeholder]]=None) – License information for the deposition.
embargo_date (Optional[Union[str,Placeholder]]=None) – Date when the deposition will become publicly accessible.
access_conditions (Optional[Union[str,Placeholder]]=None) – Custom access conditions.
publication_date (Optional[Union[str,Placeholder]]=None) – Date of publication.
**kwargs – Additional custom metadata parameters that can be set when creating an instance of this metadata class. Users can provide any extra metadata fields they need, but it is recommended to consult the Zenodo API reference for a complete list of allowed metadata parameters. Consult the Zenodo API reference for a comprehensive list of supported metadata fields and their descriptions.

classmethod from_file(file: str) → Self¶

Create a PhysicalObject metadata instance from a JSON file.

Parameters:

file (str) – The path to a JSON file containing metadata.

Returns:

An instance of the metadata class populated with the data from the JSON file.

Return type:

PhysicalObject

Raises:

TypeError – If the JSON file has an invalid format.
ValueError – If the upload_type in the metadata is not supported.

class zen.metadata.Placeholder(name: str)¶

Bases: dict

Represents a dictionary placeholder for Zenodo metadata.

This class defines a placeholder for Zenodo metadata. It is designed to create a dictionary with a specific structure, primarily used for creating dictionary placeholders in Zenodo metadata. When you create an instance of the Placeholder class and provide a placeholder name as an argument, it returns a dictionary with the structure {‘$ref’: ‘zen:<name>’}.

Parameters:: name (str) – The name of the placeholder.

Examples

Create a metadata for publication with two placeholders (‘the_title’ and ‘the_description’)

>>> from zen.metadata import Publication, Placeholder
>>> meta = Publication(
...     publication_type='article',
...     title=Placeholder('the_title'),
...     description=Placeholder('the_description')
... )
>>> print(meta.placeholders)
{'the_title', 'the_description'}

Rendering metadata

>>> replacements = {
...     'the_title': 'any title',
...     'the_description': 'any description'
... }
>>> meta.render(replacements)

json_key = '$ref'¶

schema = 'zen:'¶

Bases: Metadata

Represents metadata for a Poster deposition on Zenodo.

Create a Poster metadata instance (upload_type=’poster’).

Parameters:

title (Optional[Union[str,Placeholder]]=None) – The title of the deposition.
description (Optional[Union[str,Placeholder]]=None) – Description of the deposition (allows HTML).
creators (Optional[Union[List[Dict[str,str]],Placeholder]]=None) – List of deposition creators.
access_right (Optional[Union[str,Placeholder]]=None) – Access rights for the deposition.
license (Optional[Union[str,Placeholder]]=None) – License information for the deposition.
embargo_date (Optional[Union[str,Placeholder]]=None) – Date when the deposition will become publicly accessible.
access_conditions (Optional[Union[str,Placeholder]]=None) – Custom access conditions.
publication_date (Optional[Union[str,Placeholder]]=None) – Date of publication.
**kwargs – Additional custom metadata parameters that can be set when creating an instance of this metadata class. Users can provide any extra metadata fields they need, but it is recommended to consult the Zenodo API reference for a complete list of allowed metadata parameters. Consult the Zenodo API reference for a comprehensive list of supported metadata fields and their descriptions.

classmethod from_file(file: str) → Poster¶

Create a Poster metadata instance from a JSON file.

Parameters:

file (str) – The path to a JSON file containing metadata.

Returns:

An instance of the metadata class populated with the data from the JSON file.

Return type:

Poster

Raises:

TypeError – If the JSON file has an invalid format.
ValueError – If the upload_type in the metadata is not supported.

Bases: Metadata

Represents metadata for a Presentation deposition on Zenodo.

Create a Presentation metadata instance (upload_type=’presentation’).

Parameters:

title (Optional[Union[str,Placeholder]]=None) – The title of the deposition.
description (Optional[Union[str,Placeholder]]=None) – Description of the deposition (allows HTML).
creators (Optional[Union[List[Dict[str,str]],Placeholder]]=None) – List of deposition creators.
access_right (Optional[Union[str,Placeholder]]=None) – Access rights for the deposition.
license (Optional[Union[str,Placeholder]]=None) – License information for the deposition.
embargo_date (Optional[Union[str,Placeholder]]=None) – Date when the deposition will become publicly accessible.
access_conditions (Optional[Union[str,Placeholder]]=None) – Custom access conditions.
publication_date (Optional[Union[str,Placeholder]]=None) – Date of publication.
**kwargs – Additional custom metadata parameters that can be set when creating an instance of this metadata class. Users can provide any extra metadata fields they need, but it is recommended to consult the Zenodo API reference for a complete list of allowed metadata parameters. Consult the Zenodo API reference for a comprehensive list of supported metadata fields and their descriptions.

classmethod from_file(file: str) → Self¶

Create a Presentation metadata instance from a JSON file.

Parameters:

file (str) – The path to a JSON file containing metadata.

Returns:

An instance of the metadata class populated with the data from the JSON file.

Return type:

Presentation

Raises:

TypeError – If the JSON file has an invalid format.
ValueError – If the upload_type in the metadata is not supported.

Bases: Metadata

Represents metadata for a Publication deposition on Zenodo.

Create a Publication metadata instance (upload_type=’publication’).

Parameters:

publication_type (str) – Type of the publication. One of Publication.publication_types.
title (Optional[Union[str,Placeholder]]=None) – The title of the deposition.
description (Optional[Union[str,Placeholder]]=None) – Description of the deposition (allows HTML).
creators (Optional[Union[List[Dict[str,str]],Placeholder]]=None) – List of deposition creators.
access_right (Optional[Union[str,Placeholder]]=None) – Access rights for the deposition.
license (Optional[Union[str,Placeholder]]=None) – License information for the deposition.
embargo_date (Optional[Union[str,Placeholder]]=None) – Date when the deposition will become publicly accessible.
access_conditions (Optional[Union[str,Placeholder]]=None) – Custom access conditions.
publication_date (Optional[Union[str,Placeholder]]=None) – Date of publication.
**kwargs – Additional custom metadata parameters that can be set when creating an instance of this metadata class. Users can provide any extra metadata fields they need, but it is recommended to consult the Zenodo API reference for a complete list of allowed metadata parameters. Consult the Zenodo API reference for a comprehensive list of supported metadata fields and their descriptions.

classmethod from_file(file: str) → Self¶

Create a Publication metadata instance from a JSON file.

Parameters:

file (str) – The path to a JSON file containing metadata.

Returns:

An instance of the metadata class populated with the data from the JSON file.

Return type:

Publication

Raises:

TypeError – If the JSON file has an invalid format.
ValueError – If the upload_type in the metadata is not supported.

publication_types = ['annotationcollection', 'book', 'section', 'conferencepaper', 'datamanagementplan', 'article', 'patent', 'preprint', 'deliverable', 'milestone', 'proposal', 'report', 'softwaredocumentation', 'taxonomictreatment', 'technicalnote', 'thesis', 'workingpaper', 'other']¶

class zen.metadata.References(data: Dict[str, Any])¶

Bases: _MetaBaseListString

Represents a list of references associated with a Zenodo deposition.

This helper class provides methods for managing and manipulating references.

Parameters:: data (Dict[str,Any]) – The dictionary representing the deposition metadata.

add(reference: str) → References¶

Add a reference to the list.

Parameters:: reference (str) – The reference to add.
Returns:: The updated References instance.
Return type:: References
Raises:: ValueError – If the provided reference is not a string.

classmethod new(reference: str) → str¶

Create a new reference entry.

Parameters:: reference (str) – The reference to create.
Returns:: The reference.
Return type:: str
Raises:: ValueError – If the provided reference is not a string.

class zen.metadata.RelatedIdent(data: Dict[str, Any])¶

Bases: _MetaBaseListObject

Represents a list of related identifiers associated with a Zenodo deposition.

This helper class provides methods for managing and manipulating related identifiers, their relations, and resource types.

Parameters:: data (Dict[str,Any]) – The dictionary representing the deposition metadata.

add(identifier: str, relation: str, resource_type: str) → RelatedIdent¶

Add a new related identifier entry to the list.

Parameters:

identifier (str) – The related identifier (e.g., DOI, Handle, ARK, etc.).
relation (str) – The relation between the identifier and the deposition.
resource_type (str) – The type of the related resource.

Returns:

The updated RelatedIdent instance.

Return type:

RelatedIdent

Raises:

ValueError – If the provided identifier, relation, or resource type is not supported.

clear() → RelatedIdent¶

Clears the related identifier list.

Empty related identifier list.

Returns:: An empty RelatedIdent object.
Return type:: RelatedIdent

classmethod new(identifier: str, relation: str, resource_type: str) → Dict[str, str]¶

Create a new related identifier entry.

Parameters:

identifier (str) – The related identifier (e.g., DOI, Handle, ARK, etc.).
relation (str) – The relation between the identifier and the deposition.
resource_type (str) – The type of the related resource.

Returns:

A dictionary representing the related identifier entry.

Return type:

Dict[str,str]

Raises:

ValueError – If the provided identifier, relation, or resource type is not supported.

relations = ['isCitedBy', 'cites', 'isSupplementTo', 'isSupplementedBy', 'isContinuedBy', 'continues', 'isDescribedBy', 'describes', 'hasMetadata', 'isMetadataFor', 'isNewVersionOf', 'isPreviousVersionOf', 'isPartOf', 'hasPart', 'isReferencedBy', 'references', 'isDocumentedBy', 'documents', 'isCompiledBy', 'compiles', 'isVariantFormOf', 'isOriginalFormOf', 'isIdenticalTo', 'isAlternateIdentifier', 'isReviewedBy', 'reviews', 'isDerivedFrom', 'isSourceOf', 'requires', 'isRequiredBy', 'isObsoletedBy', 'obsoletes']¶

supported_identifiers = ['DOI', 'Handle', 'ARK', 'PURL', 'ISSN', 'ISBN', 'PubMed ID', 'PubMed Central ID', 'ADS Bibliographic Code', 'arXiv', 'Life Science Identifiers (LSID)', 'EAN-13', 'ISTC', 'URNs and URLs']¶

Bases: Metadata

Represents metadata for a Software deposition on Zenodo.

Create a Software metadata instance (upload_type=’software’).

Parameters:

title (Optional[Union[str,Placeholder]]=None) – The title of the deposition.
description (Optional[Union[str,Placeholder]]=None) – Description of the deposition (allows HTML).
creators (Optional[Union[List[Dict[str,str]],Placeholder]]=None) – List of deposition creators.
access_right (Optional[Union[str,Placeholder]]=None) – Access rights for the deposition.
license (Optional[Union[str,Placeholder]]=None) – License information for the deposition.
embargo_date (Optional[Union[str,Placeholder]]=None) – Date when the deposition will become publicly accessible.
access_conditions (Optional[Union[str,Placeholder]]=None) – Custom access conditions.
publication_date (Optional[Union[str,Placeholder]]=None) – Date of publication.
**kwargs – Additional custom metadata parameters that can be set when creating an instance of this metadata class. Users can provide any extra metadata fields they need, but it is recommended to consult the Zenodo API reference for a complete list of allowed metadata parameters. Consult the Zenodo API reference for a comprehensive list of supported metadata fields and their descriptions.

classmethod from_file(file: str) → Self¶

Create a Software metadata instance from a JSON file.

Parameters:

file (str) – The path to a JSON file containing metadata.

Returns:

An instance of the metadata class populated with the data from the JSON file.

Return type:

Software

Raises:

TypeError – If the JSON file has an invalid format.
ValueError – If the upload_type in the metadata is not supported.

class zen.metadata.Subjects(data: Dict[str, Any])¶

Bases: _MetaBaseListObject

Represents a list of subjects associated with a Zenodo deposition.

This helper class provides methods for managing and manipulating subject information, including term, identifier, and scheme.

Parameters:: data (Dict[str,Any]) – The dictionary representing the deposition metadata.

add(term: str, identifier: str, scheme: str | None = None) → Subjects¶

Add a subject entry to the list.

Parameters:

term (str) – The subject term.
identifier (str) – The subject identifier.
scheme (Optional[str]=None) – The subject scheme (if available).

Returns:

The updated Subjects instance.

Return type:

Subjects

clear() → Subjects¶

Clears the subject list.

Empty subject list.

Returns:: An empty Subjects object.
Return type:: Subjects

classmethod new(term: str, identifier: str, scheme: str | None = None) → Dict[str, str]¶

Create a new subject entry.

Parameters:

term (str) – The subject term.
identifier (str) – The subject identifier.
scheme (Optional[str]=None) – The subject scheme (if available).

Returns:

A dictionary representing the subject entry.

Return type:

Dict[str,str]

class zen.metadata.ThesisSupervisors(data: Dict[str, Any])¶

Bases: _MetaBaseListObject

Represents a list of thesis supervisors associated with a Zenodo deposition.

This helper class provides methods for managing a list of thesis supervisors.

Parameters:: data (Dict[str,Any]) – The dictionary representing the deposition metadata.

add(name: str, affiliation: str | None = None, orcid: str | None = None, gnd: str | None = None) → ThesisSupervisors¶

Adds a new supervisor to the list.

Adds a new supervisor to the list with the provided information and returns the updated ThesisSupervisors object.

Parameters:

name (str) – The name of the supervisor.
affiliation (Optional[str]) – The affiliation of the supervisor. Default is None.
orcid (Optional[str]) – The ORCID identifier of the supervisor. Default is None.
gnd (Optional[str]) – The GND identifier of the supervisor. Default is None.

Returns:

An updated ThesisSupervisors object with the new supervisor added: to the list.

Return type:

ThesisSupervisors

clear() → ThesisSupervisors¶

Clears the supervisor list.

Empty supervisor list.

Returns:: An empty ThesisSupervisors object.
Return type:: ThesisSupervisors

classmethod new(name: str, affiliation: str | None = None, orcid: str | None = None, gnd: str | None = None) → Dict[str, str]¶

Creates a new supervisor dictionary.

Creates a new supervisor with the provided information and returns the supervisor’s data as a dictionary.

Parameters:

name (str) – The name of the supervisor.
affiliation (Optional[str]) – The affiliation of the supervisor. Default is None.
orcid (Optional[str]) – The ORCID identifier of the supervisor. Default is None.
gnd (Optional[str]) – The GND identifier of the supervisor. Default is None.

Returns:

A dictionary containing the supervisor’s data.

Return type:

Dict[str,str]

Bases: Metadata

Represents metadata for a Video deposition on Zenodo.

Create a Video metadata instance (upload_type=’video’).

Parameters:

title (Optional[Union[str,Placeholder]]=None) – The title of the deposition.
description (Optional[Union[str,Placeholder]]=None) – Description of the deposition (allows HTML).
creators (Optional[Union[List[Dict[str,str]],Placeholder]]=None) – List of deposition creators.
access_right (Optional[Union[str,Placeholder]]=None) – Access rights for the deposition.
license (Optional[Union[str,Placeholder]]=None) – License information for the deposition.
embargo_date (Optional[Union[str,Placeholder]]=None) – Date when the deposition will become publicly accessible.
access_conditions (Optional[Union[str,Placeholder]]=None) – Custom access conditions.
publication_date (Optional[Union[str,Placeholder]]=None) – Date of publication.
**kwargs – Additional custom metadata parameters that can be set when creating an instance of this metadata class. Users can provide any extra metadata fields they need, but it is recommended to consult the Zenodo API reference for a complete list of allowed metadata parameters. Consult the Zenodo API reference for a comprehensive list of supported metadata fields and their descriptions.

classmethod from_file(file: str) → Self¶

Create a Video metadata instance from a JSON file.

Parameters:

file (str) – The path to a JSON file containing metadata.

Returns:

An instance of the metadata class populated with the data from the JSON file.

Return type:

Video

Raises:

TypeError – If the JSON file has an invalid format.
ValueError – If the upload_type in the metadata is not supported.

metadata module¶

zen

Navigation

Related Topics