# ebookmeta
Ebookmeta is a Python library for managing epub2, epub3 and fb2 files metadata.
Library allows you to read and write some of the metadata fields of epub2, epub3 and fb2 files.
The following fields can be read: identifier, title, authors, tags, book series and series index, language, description, translators, and cover data (image as byte array, file name, and media type).
It is possible to write all fields, excluding description and identifier.
When changing the cover, the library does not check whether the image byte array matches the media type. You must ensure that this data is correct.
There is a limitation for epub files: you can't add cover if it doesn't exist in file. You can only replace an existing cover.
This library used in my other project [Libro2](https://github.com/dnkorpushov/libro2) - GUI tool for editing metadata, rename and convert to other formats for ebook files.
## Installation
### Using pip
```pip3 install ebookmeta```
### From source
```python3 setup.py install```
### Requirements
* lxml
## Usage
### Reading
```python
import ebookmeta
meta = ebookmeta.get_metadata('test.epub') # returning Metadata class
print(meta.title)
for author in metadata.authors:
print(author)
```
### Writing
```python
import ebookmeta
meta = ebookmeta.get_metadata('test.epub')
meta.title = 'New book title'
meta.set_author_list(['Isaac Azimov, Arthur Charles Clarke'])
ebookmeta.set_metadata('test.epub', meta) # Set epub metadata from Metadata class
```
## Metadata class
### Attributes
* identifier - book unique identifier
* title - book title
* author_list - list of book authors
* series - book series title
* series_index - book series index
* tag_list - book tag list
* lang - book language
* description - book description
* translators - book translators (if exists)
* format - file format (epub or fb2)
* format_version - format specification version
* cover_image_data - cover image byte array
* cover_media_type - cover media type (possible image/jpeg, image/png)
* cover_file_name - stored file name
* file - source file name
* file_created - file creation time in ISO datetime format
* file_modified - file modification time in ISO datetime format
#### Additional attributes for fb2
* publish_info.title - published book title
* publish_info.publisher - original book bublisher
* publish_info.city - city where original book was published
* publish_info.year - year of publication book
* publish_info.isbn - International Standard Book Number (ISBN)
* publish_info.series - original book sereis
* publish_info.seires_index - original book series index
### Methods
* author_list_to_string - return authors list as comma-separated string
* translator_list_to_string - return translators list as comma-separated string
* tag_list_to_string - return tag list as comma-separated string
* tag_description_list_to_string - for fb2 return tag description list as comma-separated string, for epub same tag_list_to_string data
* set_author_list_from_string - sets authors list from comma-separated string
* set_translator_list_from_string - sets translators list from comma-separated string
* set_tag_list_from_string - sets tags list from comma-separated string
* get_filename_by_pattern - returns the file name generated based on the metadata according to the given template
### Metadata.get_filename_by_pattern method
Metadata.**get_filename_by_pattern**(filename_pattern, author_pattern)
Return the filename, based on template.
Template can contain placeholders, path delimiters, and any other characters that are included in the output without modification.
Usage:
```
meta = ebook.get_metadata('oldfilename.epub')
new_filename = meta.get_filename_by_pattern('#Author. #Title', '#l{ #fi.}')
```
For example, for epub Azimov's Foundation book, return "Azimov I. Foundation.epub" string.
You can group template parts into optional blocks. An optional block is denoted with curly braces {}. An optional block must contain only one placeholder and any number of other characters. The optional block is completely excluded from the result if the value of the placeholder is None. Optional blocks can't be nested.
Usage:
```
meta1 = ebook.get_metadata('book_with_series.epub')
meta2 = ebook.get_metadata('book_without_series.epub')
meta1.get_filename_by_pattern('/books/#Author/{#Series/}{#Number. }#Title', '#l{ #fi.}')
meta2.get_filename_by_pattern('/books/#Author/{#Series/}{#Number. }#Title', '#l{ #fi.}')
```
For example, for epub Azimov's Foundation book if metadata contains series and series_index (Foundation 1), return "/books/Azimov I/Foundation/1. Foundation.epub".
For epub Azimov,s I, robot return "/books/Azimov I/I, robot.epub".
Possible filename placeholders:
- #Title - book title
- #Author - Book author name generated by author pattern. If the book contains more than one author, the "et al" is added at the end of the line. For russian language is "Рё РґСЂ".
- #Authors - comma separated list of all book authors. Each author name generated by author pattern. Be careful, if book contain long list of authors.
- #Series - book series title
- #Abbrseries - abbriviated series title. E.g. for "Very long series title" #abbrseries is "Vlst".
- #Number - book series index
- #Padnumber padding left book series index
- #Translator - last name of first book translator
- #Atranslator - book translator name, generate by #Author rules
= #Atranslators - comma separated list of all book tranlsators by #Authors rules
- #Bookid - book unique identifier
- #Md5 - md5 checksum for source file
РЈou can change the letter case of the placeholder value, just put the placeholder name in the right case.
For example:
- #Title - get book title as is
- #TITLE - get book title in UPPER CASE
- #title - get book title in lower case
Possible author name placeholders:
- #f - author first name. Для русского языка - имя автора.
- #m - author middle name. Для русского языка - отчество автора.
- #l - author last name. Для русского языка - фамилия автора.
- #fi - first name initial. Для русского языка - инициал имени.
- #mi - middle name initial. Для русского языка - инициал отчества.
Raw data
{
"_id": null,
"home_page": "https://github.com/dnkorpushov/ebookmeta",
"name": "ebookmeta",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "ebook,epub,metadata,fb2",
"author": "Dmitrii Korpushov",
"author_email": "dnkorpushov@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/f8/5f/715c3e8ecce7e6d4dadd873ae8d3caf6f92b95c2bffd5b0ec21d89b2080c/ebookmeta-1.2.11.tar.gz",
"platform": null,
"description": "# ebookmeta\r\n\r\nEbookmeta is a Python library for managing epub2, epub3 and fb2 files metadata.\r\n\r\nLibrary allows you to read and write some of the metadata fields of epub2, epub3 and fb2 files.\r\n\r\nThe following fields can be read: identifier, title, authors, tags, book series and series index, language, description, translators, and cover data (image as byte array, file name, and media type).\r\nIt is possible to write all fields, excluding description and identifier.\r\n\r\nWhen changing the cover, the library does not check whether the image byte array matches the media type. You must ensure that this data is correct.\r\n\r\nThere is a limitation for epub files: you can't add cover if it doesn't exist in file. You can only replace an existing cover.\r\n\r\nThis library used in my other project [Libro2](https://github.com/dnkorpushov/libro2) - GUI tool for editing metadata, rename and convert to other formats for ebook files.\r\n\r\n## Installation\r\n### Using pip\r\n```pip3 install ebookmeta```\r\n### From source\r\n```python3 setup.py install```\r\n### Requirements\r\n* lxml\r\n\r\n## Usage\r\n\r\n### Reading\r\n```python\r\nimport ebookmeta\r\n\r\nmeta = ebookmeta.get_metadata('test.epub') # returning Metadata class\r\nprint(meta.title)\r\nfor author in metadata.authors:\r\n print(author)\r\n```\r\n\r\n### Writing\r\n```python\r\nimport ebookmeta\r\n\r\nmeta = ebookmeta.get_metadata('test.epub')\r\nmeta.title = 'New book title'\r\nmeta.set_author_list(['Isaac Azimov, Arthur Charles Clarke'])\r\n\r\nebookmeta.set_metadata('test.epub', meta) # Set epub metadata from Metadata class\r\n```\r\n\r\n## Metadata class\r\n\r\n### Attributes\r\n* identifier - book unique identifier\r\n* title - book title\r\n* author_list - list of book authors\r\n* series - book series title\r\n* series_index - book series index\r\n* tag_list - book tag list\r\n* lang - book language\r\n* description - book description\r\n* translators - book translators (if exists)\r\n* format - file format (epub or fb2)\r\n* format_version - format specification version \r\n* cover_image_data - cover image byte array\r\n* cover_media_type - cover media type (possible image/jpeg, image/png)\r\n* cover_file_name - stored file name\r\n* file - source file name\r\n* file_created - file creation time in ISO datetime format\r\n* file_modified - file modification time in ISO datetime format\r\n\r\n#### Additional attributes for fb2 \r\n* publish_info.title - published book title\r\n* publish_info.publisher - original book bublisher\r\n* publish_info.city - city where original book was published\r\n* publish_info.year - year of publication book\r\n* publish_info.isbn - International Standard Book Number (ISBN)\r\n* publish_info.series - original book sereis\r\n* publish_info.seires_index - original book series index\r\n\r\n### Methods \r\n* author_list_to_string - return authors list as comma-separated string\r\n* translator_list_to_string - return translators list as comma-separated string\r\n* tag_list_to_string - return tag list as comma-separated string\r\n* tag_description_list_to_string - for fb2 return tag description list as comma-separated string, for epub same tag_list_to_string data\r\n* set_author_list_from_string - sets authors list from comma-separated string\r\n* set_translator_list_from_string - sets translators list from comma-separated string\r\n* set_tag_list_from_string - sets tags list from comma-separated string\r\n* get_filename_by_pattern - returns the file name generated based on the metadata according to the given template\r\n\r\n\r\n### Metadata.get_filename_by_pattern method\r\nMetadata.**get_filename_by_pattern**(filename_pattern, author_pattern)\r\nReturn the filename, based on template.\r\nTemplate can contain placeholders, path delimiters, and any other characters that are included in the output without modification. \r\nUsage:\r\n```\r\nmeta = ebook.get_metadata('oldfilename.epub')\r\nnew_filename = meta.get_filename_by_pattern('#Author. #Title', '#l{ #fi.}')\r\n```\r\nFor example, for epub Azimov's Foundation book, return \"Azimov I. Foundation.epub\" string.\r\n\r\nYou can group template parts into optional blocks. An optional block is denoted with curly braces {}. An optional block must contain only one placeholder and any number of other characters. The optional block is completely excluded from the result if the value of the placeholder is None. Optional blocks can't be nested.\r\nUsage:\r\n```\r\nmeta1 = ebook.get_metadata('book_with_series.epub')\r\nmeta2 = ebook.get_metadata('book_without_series.epub')\r\nmeta1.get_filename_by_pattern('/books/#Author/{#Series/}{#Number. }#Title', '#l{ #fi.}')\r\nmeta2.get_filename_by_pattern('/books/#Author/{#Series/}{#Number. }#Title', '#l{ #fi.}')\r\n\r\n```\r\nFor example, for epub Azimov's Foundation book if metadata contains series and series_index (Foundation 1), return \"/books/Azimov I/Foundation/1. Foundation.epub\".\r\nFor epub Azimov,s I, robot return \"/books/Azimov I/I, robot.epub\".\r\n\r\nPossible filename placeholders:\r\n- #Title - book title\r\n- #Author - Book author name generated by author pattern. If the book contains more than one author, the \"et al\" is added at the end of the line. For russian language is \"\u0420\u0451 \u0420\u0491\u0421\u0402\".\r\n- #Authors - comma separated list of all book authors. Each author name generated by author pattern. Be careful, if book contain long list of authors.\r\n- #Series - book series title\r\n- #Abbrseries - abbriviated series title. E.g. for \"Very long series title\" #abbrseries is \"Vlst\".\r\n- #Number - book series index\r\n- #Padnumber padding left book series index\r\n- #Translator - last name of first book translator\r\n- #Atranslator - book translator name, generate by #Author rules\r\n= #Atranslators - comma separated list of all book tranlsators by #Authors rules\r\n- #Bookid - book unique identifier\r\n- #Md5 - md5 checksum for source file \r\n\r\n\u0420\u0408ou can change the letter case of the placeholder value, just put the placeholder name in the right case.\r\nFor example:\r\n- #Title - get book title as is\r\n- #TITLE - get book title in UPPER CASE\r\n- #title - get book title in lower case\r\n\r\nPossible author name placeholders:\r\n- #f - author first name. \u0420\u201d\u0420\u00bb\u0421\u040f \u0421\u0402\u0421\u0453\u0421\u0403\u0421\u0403\u0420\u0454\u0420\u0455\u0420\u0456\u0420\u0455 \u0421\u040f\u0420\u00b7\u0421\u2039\u0420\u0454\u0420\u00b0 - \u0420\u0451\u0420\u0458\u0421\u040f \u0420\u00b0\u0420\u0406\u0421\u201a\u0420\u0455\u0421\u0402\u0420\u00b0.\r\n- #m - author middle name. \u0420\u201d\u0420\u00bb\u0421\u040f \u0421\u0402\u0421\u0453\u0421\u0403\u0421\u0403\u0420\u0454\u0420\u0455\u0420\u0456\u0420\u0455 \u0421\u040f\u0420\u00b7\u0421\u2039\u0420\u0454\u0420\u00b0 - \u0420\u0455\u0421\u201a\u0421\u2021\u0420\u00b5\u0421\u0403\u0421\u201a\u0420\u0406\u0420\u0455 \u0420\u00b0\u0420\u0406\u0421\u201a\u0420\u0455\u0421\u0402\u0420\u00b0.\r\n- #l - author last name. \u0420\u201d\u0420\u00bb\u0421\u040f \u0421\u0402\u0421\u0453\u0421\u0403\u0421\u0403\u0420\u0454\u0420\u0455\u0420\u0456\u0420\u0455 \u0421\u040f\u0420\u00b7\u0421\u2039\u0420\u0454\u0420\u00b0 - \u0421\u201e\u0420\u00b0\u0420\u0458\u0420\u0451\u0420\u00bb\u0420\u0451\u0421\u040f \u0420\u00b0\u0420\u0406\u0421\u201a\u0420\u0455\u0421\u0402\u0420\u00b0.\r\n- #fi - first name initial. \u0420\u201d\u0420\u00bb\u0421\u040f \u0421\u0402\u0421\u0453\u0421\u0403\u0421\u0403\u0420\u0454\u0420\u0455\u0420\u0456\u0420\u0455 \u0421\u040f\u0420\u00b7\u0421\u2039\u0420\u0454\u0420\u00b0 - \u0420\u0451\u0420\u0405\u0420\u0451\u0421\u2020\u0420\u0451\u0420\u00b0\u0420\u00bb \u0420\u0451\u0420\u0458\u0420\u00b5\u0420\u0405\u0420\u0451.\r\n- #mi - middle name initial. \u0420\u201d\u0420\u00bb\u0421\u040f \u0421\u0402\u0421\u0453\u0421\u0403\u0421\u0403\u0420\u0454\u0420\u0455\u0420\u0456\u0420\u0455 \u0421\u040f\u0420\u00b7\u0421\u2039\u0420\u0454\u0420\u00b0 - \u0420\u0451\u0420\u0405\u0420\u0451\u0421\u2020\u0420\u0451\u0420\u00b0\u0420\u00bb \u0420\u0455\u0421\u201a\u0421\u2021\u0420\u00b5\u0421\u0403\u0421\u201a\u0420\u0406\u0420\u00b0.\r\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Read/write ebook metadata for fb2, epub2 and epub3 files",
"version": "1.2.11",
"split_keywords": [
"ebook",
"epub",
"metadata",
"fb2"
],
"urls": [
{
"comment_text": "",
"digests": {
"md5": "63316f6e1d07f562990c2868e1c62405",
"sha256": "75ccdca8f99f1b3d4f3aaa3ba3ae529a3f4373e495144d43f8513df010fe76c4"
},
"downloads": -1,
"filename": "ebookmeta-1.2.11-py3-none-any.whl",
"has_sig": false,
"md5_digest": "63316f6e1d07f562990c2868e1c62405",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 40108,
"upload_time": "2022-12-10T17:49:09",
"upload_time_iso_8601": "2022-12-10T17:49:09.858326Z",
"url": "https://files.pythonhosted.org/packages/0c/48/e6d15f7a9d98f7eee543e8e0720e64add22ef05eec734a79eef1c2bafbd0/ebookmeta-1.2.11-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"md5": "612f21254bc808ad74f390914d39d355",
"sha256": "94abd0e8c82a4d3f8ebecf0086ad0fb60c70bbb928ee9c55c4553bbb9ed1c74d"
},
"downloads": -1,
"filename": "ebookmeta-1.2.11.tar.gz",
"has_sig": false,
"md5_digest": "612f21254bc808ad74f390914d39d355",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 40219,
"upload_time": "2022-12-10T17:49:12",
"upload_time_iso_8601": "2022-12-10T17:49:12.421698Z",
"url": "https://files.pythonhosted.org/packages/f8/5f/715c3e8ecce7e6d4dadd873ae8d3caf6f92b95c2bffd5b0ec21d89b2080c/ebookmeta-1.2.11.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2022-12-10 17:49:12",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "dnkorpushov",
"github_project": "ebookmeta",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "ebookmeta"
}
JSON
