# bibparse -- read and write BibTeX files
## Description
`bibparse` reads and writes BibTeX files.
The main class, `Biblio`, is a `dict` with methods for parsing, reading, writing and searching for BibTeX data. Each entry in the `Biblio` is another kind of special dict, `BibItem`. The user usually only needs to access `Biblio`.
**NOTE** Just because I use only `{...}` myself, I’ve never thought of adding the more traditional `"..."` field marking before version 1.2.*.
## Current version
Version 1.2.0-dev.9 -- 29 July 2021.
## Copyrights
Copyright © 2019–2021 Legisign.org <mailto:software@legisign.org>
This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with this program. If not, see <https://www.gnu.org/licenses/>.
## Example usage
import bibparse
db = bibparse.Biblio(filename)
print(db)
The sample code loads, parses and pretty-prints a BibTeX file.
## Module contents
### 1. Helper functions
The values in some fields (namely author, editor, translator, publisher, address, and pages, all of which may have several names, locations, or other data in their values) of `BibItem` are stored internally as `list`s.
* `to_bibtex(key, val)` -- convert an internal Python value into a BibTeX string
* `to_python(key, val)` -- convert a BibTeX string into an internal Python value
Both functions take a BibTeX field name (key) in order to decide how to handle the value. Except for "pages" where the separator is a single dash "-", the separator is the string " and ", the leading and trailing whitespace included.
Examples:
* `to_bibtex('pages', [100, 110])` → '100-110'
* `to_python('address', 'London and New York')` → ['London', 'New York']
### 2. Exceptions
* `BibError` -- the base exception
* `DuplicateError` -- duplicate ID’s
* `NoIDError` -- missing ID in an entry
* `PreambleError` -- invalid preamble
Each exception has a property `lineno` in order to refer to the line that has raised the exception:
try:
db = bibparse.Biblio(filename)
except bibparse.DuplicateError as exc:
print(f'duplicate bibid on line {exc.lineno}')
### 3. BibItem class
A `dict`-derived object representing a single BibTeX entry.
#### 3.1 Methods
These are derived from `dict` but modified to ensure lower-case keys, reasonable ordering of keys in a printout, and sort ordering.
* `__lt__()`
* `__repr__()`
* `__setitem__()`
* `parse(data)` -- parse string data into a BibTeX entry
* `update()` -- update `Biblio` using another object
`parse()` can be manually called for `str` input.
`update()` has an additional optional `overwrite=bool` parameter. If `True` (the default), `update()` functions exactly like `dict.update()`, updating BibItem contents from data in the supplied `dict`. If `False`, only new keys in supplied data is added but existing values are not overwritten.
### 4. Biblio class
The main class. The constructor can be given an optional filename argument; the file is opened and parsed automatically.
#### 4.1 Methods
The `__repr__()` method is provided so that merely `print()`ing the `Biblio` object produces valid BibTeX output.
* `by_bibid(bibids)` -- return all entries whose bibid is in the list (or set)
* `by_regex(field, regex)` -- search in field by regex
* `by_types(bibtypes, complement=False)` -- search by BibTeX type
* `parse(data)` -- parse string as BibTeX data
* `read(filename)` -- read and parse file as BibTeX data
* `write(filename)` -- write file in BibTeX format
`parse()` can be manually called for `str` input; however, `read()` automatically calls it, as does the constructor `Biblio()` when given a filename argument.
`by_bibid(bibids)` was written in order to make combining searches easier. Each `by_regex()` call returns a `Biblio` object whose keys can be obtained with `Biblio.keys()`. These keys can be used in `set` operations to provide a new list of keys that match either any (intersection) or all (union) of the keys, and `by_bibid()` can then be used to return all the entries.
`by_regex(field, regex)` searches the database by field values and returns the matches in a new `Biblio` object. E.g., `by_regex('author', '.*Smith.*')` returns all entries where the "author" field contains "Smith".
`by_types(bibtypes, complement=False)` searches the database by BibTeX types (given without the initial `"@"`) and returns the matches in a new `Biblio` object. `bibtypes` can be a string specifying a single type (e.g., `"article"`) or a list of strings specifying several types (e.g., `["article", "book"]`). If the optional `complement` parameter is set to True, the function returns the complement, i.e., all entries _not_ matching the criteria.
Raw data
{
"_id": null,
"home_page": "http://github.com/Legisign/bibparse",
"name": "bibparse",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "",
"author": "Legisign.org",
"author_email": "software@legisign.org",
"download_url": "https://files.pythonhosted.org/packages/3d/42/2074d94e853075a747fc196f015612f65aa510b325981ad748cb5fdc927c/bibparse-1.2.0.tar.gz",
"platform": null,
"description": "# bibparse -- read and write BibTeX files\n\n## Description\n\n`bibparse` reads and writes BibTeX files.\n\nThe main class, `Biblio`, is a `dict` with methods for parsing, reading, writing and searching for BibTeX data. Each entry in the `Biblio` is another kind of special dict, `BibItem`. The user usually only needs to access `Biblio`.\n\n**NOTE** Just because I use only `{...}` myself, I\u2019ve never thought of adding the more traditional `\"...\"` field marking before version 1.2.*.\n\n## Current version\n\nVersion 1.2.0-dev.9 -- 29 July 2021.\n\n## Copyrights\n\nCopyright \u00a9 2019\u20132021 Legisign.org <mailto:software@legisign.org>\n\nThis program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.\n\nThis program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.\n\nYou should have received a copy of the GNU General Public License along with this program. If not, see <https://www.gnu.org/licenses/>.\n\n## Example usage\n\n import bibparse\n db = bibparse.Biblio(filename)\n print(db)\n\nThe sample code loads, parses and pretty-prints a BibTeX file.\n\n## Module contents\n\n### 1. Helper functions\n\nThe values in some fields (namely author, editor, translator, publisher, address, and pages, all of which may have several names, locations, or other data in their values) of `BibItem` are stored internally as `list`s.\n\n* `to_bibtex(key, val)` -- convert an internal Python value into a BibTeX string\n* `to_python(key, val)` -- convert a BibTeX string into an internal Python value\n\nBoth functions take a BibTeX field name (key) in order to decide how to handle the value. Except for \"pages\" where the separator is a single dash \"-\", the separator is the string \" and \", the leading and trailing whitespace included.\n\nExamples:\n\n* `to_bibtex('pages', [100, 110])` \u2192 '100-110'\n* `to_python('address', 'London and New York')` \u2192 ['London', 'New York']\n\n### 2. Exceptions\n\n* `BibError` -- the base exception\n * `DuplicateError` -- duplicate ID\u2019s\n * `NoIDError` -- missing ID in an entry\n * `PreambleError` -- invalid preamble\n\nEach exception has a property `lineno` in order to refer to the line that has raised the exception:\n\n try:\n db = bibparse.Biblio(filename)\n except bibparse.DuplicateError as exc:\n print(f'duplicate bibid on line {exc.lineno}')\n\n### 3. BibItem class\n\nA `dict`-derived object representing a single BibTeX entry.\n\n#### 3.1 Methods\n\nThese are derived from `dict` but modified to ensure lower-case keys, reasonable ordering of keys in a printout, and sort ordering.\n\n* `__lt__()`\n* `__repr__()`\n* `__setitem__()`\n* `parse(data)` -- parse string data into a BibTeX entry\n* `update()` -- update `Biblio` using another object\n\n`parse()` can be manually called for `str` input.\n\n`update()` has an additional optional `overwrite=bool` parameter. If `True` (the default), `update()` functions exactly like `dict.update()`, updating BibItem contents from data in the supplied `dict`. If `False`, only new keys in supplied data is added but existing values are not overwritten.\n\n### 4. Biblio class\n\nThe main class. The constructor can be given an optional filename argument; the file is opened and parsed automatically.\n\n#### 4.1 Methods\n\nThe `__repr__()` method is provided so that merely `print()`ing the `Biblio` object produces valid BibTeX output.\n\n* `by_bibid(bibids)` -- return all entries whose bibid is in the list (or set)\n* `by_regex(field, regex)` -- search in field by regex\n* `by_types(bibtypes, complement=False)` -- search by BibTeX type\n* `parse(data)` -- parse string as BibTeX data\n* `read(filename)` -- read and parse file as BibTeX data\n* `write(filename)` -- write file in BibTeX format\n\n`parse()` can be manually called for `str` input; however, `read()` automatically calls it, as does the constructor `Biblio()` when given a filename argument.\n\n`by_bibid(bibids)` was written in order to make combining searches easier. Each `by_regex()` call returns a `Biblio` object whose keys can be obtained with `Biblio.keys()`. These keys can be used in `set` operations to provide a new list of keys that match either any (intersection) or all (union) of the keys, and `by_bibid()` can then be used to return all the entries.\n\n`by_regex(field, regex)` searches the database by field values and returns the matches in a new `Biblio` object. E.g., `by_regex('author', '.*Smith.*')` returns all entries where the \"author\" field contains \"Smith\".\n\n`by_types(bibtypes, complement=False)` searches the database by BibTeX types (given without the initial `\"@\"`) and returns the matches in a new `Biblio` object. `bibtypes` can be a string specifying a single type (e.g., `\"article\"`) or a list of strings specifying several types (e.g., `[\"article\", \"book\"]`). If the optional `complement` parameter is set to True, the function returns the complement, i.e., all entries _not_ matching the criteria.\n\n",
"bugtrack_url": null,
"license": "GPLv3",
"summary": "Read and write BibTeX files",
"version": "1.2.0",
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "68e1f09f1e69f0f9949bf6bdb1aa3988a1617c2d532d6dcb2f5ac2020f4a7a81",
"md5": "5110f6193f40f00aa3ae7e316581d7d0",
"sha256": "fe86d93e88d08cb8ce95173eababb38c65377e16b6c28783545619d9d64d395a"
},
"downloads": -1,
"filename": "bibparse-1.2.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "5110f6193f40f00aa3ae7e316581d7d0",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 19943,
"upload_time": "2023-03-24T10:51:03",
"upload_time_iso_8601": "2023-03-24T10:51:03.504232Z",
"url": "https://files.pythonhosted.org/packages/68/e1/f09f1e69f0f9949bf6bdb1aa3988a1617c2d532d6dcb2f5ac2020f4a7a81/bibparse-1.2.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "3d422074d94e853075a747fc196f015612f65aa510b325981ad748cb5fdc927c",
"md5": "fa1d844b43e4a0c5b9a12772bb5638ad",
"sha256": "aaf891e6d523567bd8b2d3e12549b363492c34551bd4f10fc47620f041d034c9"
},
"downloads": -1,
"filename": "bibparse-1.2.0.tar.gz",
"has_sig": false,
"md5_digest": "fa1d844b43e4a0c5b9a12772bb5638ad",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 19501,
"upload_time": "2023-03-24T10:51:05",
"upload_time_iso_8601": "2023-03-24T10:51:05.348596Z",
"url": "https://files.pythonhosted.org/packages/3d/42/2074d94e853075a747fc196f015612f65aa510b325981ad748cb5fdc927c/bibparse-1.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-03-24 10:51:05",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "Legisign",
"github_project": "bibparse",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "bibparse"
}
JSON
