Metadata-Version: 2.4
Name: isbntools
Version: 4.3.29
Summary: app and framework for 'all things ISBN' (International Standard Book Number) including metadata, descriptions, covers... .
Home-page: https://github.com/xlcnd/isbntools
Download-URL: https://github.com/xlcnd/isbntools/archive/v4.3.29.zip
Author: Alexandre Lima Conde
Author-email: xlcnd@outlook.com
License: LGPL v3
Project-URL: Bug Reports, https://github.com/xlcnd/isbntools/issues
Project-URL: Dev Docs, https://github.com/xlcnd/isbntools/blob/dev/README.rst#info
Project-URL: Forum, https://stackoverflow.com/search?tab=newest&q=isbntools
Project-URL: License, https://github.com/xlcnd/isbntools/blob/dev/LICENSE-LGPL-3.0.txt
Keywords: ISBN metadata Google_Books Open_Library Wikipedia BibTeX EndNote RefWorks MSWord BibJSON ISBN-A doi
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: License :: OSI Approved :: GNU Lesser General Public License v3 (LGPLv3)
Classifier: Operating System :: OS Independent
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: End Users/Desktop
Classifier: Topic :: Text Processing :: General
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Description-Content-Type: text/x-rst
License-File: LICENSE-LGPL-3.0.txt
Requires-Dist: isbnlib<3.11.0,>=3.10.9
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: download-url
Dynamic: home-page
Dynamic: keywords
Dynamic: license
Dynamic: license-file
Dynamic: project-url
Dynamic: requires-dist
Dynamic: summary


.. image:: https://github.com/xlcnd/isbntools/workflows/tests/badge.svg
    :target: https://github.com/xlcnd/isbntools/actions
    :alt: Built Status

.. image:: https://img.shields.io/github/issues/xlcnd/isbntools/bug.svg?label=bugs&style=flat
    :target: https://github.com/xlcnd/isbntools/labels/bug
    :alt: Bugs

.. image:: https://img.shields.io/pypi/dm/isbntools.svg?style=flat
    :target: https://pypi.org/project/isbntools/
    :alt: PYPI Downloads


Info
====

``isbntools`` provides several useful methods and functions
to validate, clean, transform, hyphenate and
get metadata for ISBN strings.


**For the end user** several scripts are provided to use **from the command line**:

.. code-block:: console

    $ to_isbn10 ISBN13

transforms an ISBN13 number to ISBN10.

.. code-block:: console

    $ to_isbn13 ISBN10

transforms an ISBN10 number to ISBN13.

.. code-block:: console

    $ isbn_info ISBN

gives you the *group identifier* of the ISBN.

.. code-block:: console

    $ isbn_mask ISBN

*masks* (hyphenate) an ISBN (split it by identifiers).

.. code-block:: console

    $ isbn_meta ISBN [goob|openl|merge] [bibtex|csl|msword|endnote|refworks|opf|json] [YOUR_APIKEY_TO_SERVICE]

gives you the main metadata associated with the ISBN, ``goob`` uses the **Google Books service** (**no key is needed**),
and **is the default option** (you only have to enter, e.g. ``isbn_meta 9780321534965``),
``openl`` uses the **OpenLibrary.org** api (**no key is needed**) and
``wiki`` uses the **Wikipedia** api (**no key is needed**).
You can enter API keys and
set preferences in the file ``isbntools.conf`` in your
``$HOME\.isbntools`` directory (UNIX). For Windows, you should look at
``%APPDATA%/isbntools/isbntools.conf``. The output can be formatted as ``bibtex``, ``csl`` (CSL-JSON),
``msword``, ``endnote``, ``refworks``, ``opf`` or ``json`` (BibJSON) bibliographic formats.

    **NOTE**
    You can apply this command to many ISBNs by using *posix pipes*
    (e.g. ``type FILE_WITH_ISBNs.txt | isbn_meta [SERVICE] [FORMAT] [APIKEY]`` in Windows)

    You can add more sources for metadata by installing ``isbnlib`` plugins: isbnlib-bnf_,
    isbnlib-porbase_, isbnlib-loc_, isbnlib-mcues_, isbnlib-dnb_, isbnlib-sbn_, isbnlib-kb_, ...
    (check pypi_ for available plugins).


.. code-block:: console

    $ isbn_editions ISBN

gives the collection of ISBNs that represent a given book (uses **Wikipedia** and **LibraryThing**).

.. code-block:: console

    $ isbn_validate ISBN

validates ISBN10 and ISBN13.

.. code-block:: console

    $ ... | isbn_validate

to use with *posix pipes* (e.g. ``cat FILE_WITH_ISBNs | isbn_validate`` in OSX or Linux).

    **TIP** Suppose you want to extract the ISBN of a pdf eboook (MYEBOOK.pdf).
    Install pdfminer_ and then enter in a command line::

    $ pdf2txt.py -m 5 MYEBOOK.pdf | isbn_validate


.. code-block:: console

    $ isbn_from_words "words from title and author name"

a *fuzzy* script that returns the *most probable* ISBN from a set of words!
(You can verify the result with ``isbn_meta``)!


.. code-block:: console

    $ isbn_goom "words from title and author name" [bibtex|csl|msword|endnote|refworks|json]

a script that returns from **Google Books multiple references**.


.. code-block:: console

    $ isbn_doi ISBN

returns the doi's ISBN-A code of a given ISBN.


.. code-block:: console

    $ isbn_ean13 ISBN

returns the EAN13 code of a given ISBN.


.. code-block:: console

    $ isbn_classify ISBN

returns the OCLC classifiers of a given ISBN.


.. code-block:: console

    $ isbn_ren FILENAME

renames (using metadata) files in the **current directory** that have ISBNs in their
filename (e.g. ``isbn_ren 1783559284_book.epub``, ``isbn_ren "*.pdf"``).

    Enter ``isbn_ren`` to see many other options.


.. code-block:: console

    $ isbntools

writes version and copyright notice and **checks if there are updates**.

With

.. code-block:: console

    $ isbn_repl

you will get a **REPL with history, autocompletion, fuzzy options,
redirection and access to the shell**.

Following is a typical session:

.. code-block:: console

    $ isbn_repl

        Welcome to the isbntools 4.3.29 REPL.
        ** For help type 'help' or '?'
        ** To exit type 'exit' :)
        ** To run a shell command, type '!<shellcmnd>'
        ** Use '#' in place of the last ISBN

    $ isbn> ?

    Commands available (type ?<command> to get help):
    -------------------------------------------------
    BIBFORMATS  classify  desc     ean13     from_words  info  to_isbn10
    PROVIDERS   conf      doi      editions  goom        mask  to_isbn13
    audit       cover     doi2tex  exit      help        meta  validate


    $ isbn> meta 9780156001311 tex
    @book{9780156001311,
         title = {The Name Of The Rose},
        author = {Umberto Eco},
          isbn = {9780156001311},
          year = {1994},
     publisher = {Harcourt Brace}
    }
    $ isbn> meta 9780156001311 tex >>myreferences.bib
    $ isbn> !ls
    myreferences.bib
    $ isbn> desc #
    It is the year 1327. Franciscans in an Italian abbey are suspected of
    heresy, but Brother William of Baskerville's investigation is suddenly
    overshadowed by seven bizarre deaths. Translated by William Weaver. A Helen
    and Kurt Wolff Book
    $ isbn> cover #
         thumbnail:  http://books.google.com/books/content?id=PVVyuD1UY1wC&printsec=frontcover&img=1&zoom=1
    smallThumbnail:  http://books.google.com/books/content?id=PVVyuD1UY1wC&printsec=frontcover&img=1&zoom=5
    $ isbn> PROVIDERS
    bnf  dnb  goob  kb  loc  mcues  openl  porbase  wiki
    $ isbn> exit
    bye


**Within REPL many of the operations are faster.**




Install
=======

From the command line enter (in some cases you have to precede the
command with ``sudo``):


.. code-block:: console

    $ pip install isbntools


If you use linux systems, you can install using your distribution package
manager (packages ``python-isbntools`` and ``python3-isbntools``), however
usually these packages are **very old and don't work well anymore**!



For Devs
========

If you would like to contribute to the project please read the guidelines_.


Conf File
=========

You can enter API keys and set preferences in the file ``isbntools.conf`` in your
``$HOME/.isbntools`` directory (UNIX). For Windows, you should look at
``%APPDATA%/isbntools/isbntools.conf``
(**create these, directory and file, if don't exist** [Now just enter ``isbn_conf make``!]).
The file should look like:

.. code-block:: console

    ...

    [MISC]
    REN_FORMAT={firstAuthorLastName}{year}_{title}_{isbn}
    DEBUG=False

    [SYS]
    URLOPEN_TIMEOUT=10
    THREADS_TIMEOUT=12
    LOAD_METADATA_PLUGINS=True
    LOAD_FORMATTER_PLUGINS=True

    [SERVICES]
    DEFAULT_SERVICE=goob
    VIAS_MERGE=parallel

    ...


The values are self-explanatory!


    **NOTE** If you are running ``isbntools`` inside a virtual environment, the
    ``isbntools.conf`` file will be inside folder ``isbntools``
    at the root of the environment.


The easier way to manipulate these files is by using the script ``isbn_conf``.
At a terminal enter:

.. code-block:: console

   $ isbn_conf show

to see the current conf file.

This script has many options that allow a controlled editing of the conf file.
Just enter ``isbn_conf`` for help.



Known Issues
============

1. The ``meta`` method and the ``isbn_meta`` script sometimes give a wrong result
   (this is due to errors on the chosen service), in alternative you should
   try one of the others services.

2. The ``isbntools`` works internally with unicode, however this doesn't
   solve errors of lost information due to bad encode/decode at the origin!

3. Periodically, agencies, issue new blocks of ISBNs. The
   range_ of these blocks is on a database that ``mask`` uses. So it could happen,
   if you have a version of ``isbntools`` that is too old, ``mask`` doesn't work for
   valid (recent) issued ISBNs. The solution? **Update isbntools often**!

4. Calls to metadata services are cached by default. If you don't want this
   feature, just enter ``isbn_conf setopt cache no``. If by any reason you need
   to clear the cache, just enter ``isbn_conf delcache``.

Any issue that you would like to report, please do it at github_
or at stackoverflow_ with tag **isbntools**.



.. _github: https://github.com/xlcnd/isbntools/issues

.. _range: https://www.isbn-international.org/range_file_generation

.. _guidelines: http://bit.ly/1jcxq8W

.. _pdfminer: https://pypi.python.org/pypi/pdfminer

.. _isbnlib: http://bit.ly/ISBNlib

.. _Docs: http://bit.ly/1l0W4In

.. _stackoverflow: https://stackoverflow.com/search?tab=newest&q=isbntools

.. _isbnlib-bnf: https://pypi.python.org/pypi/isbnlib-bnf

.. _isbnlib-loc: https://pypi.python.org/pypi/isbnlib-loc

.. _isbnlib-porbase: https://pypi.python.org/pypi/isbnlib-porbase

.. _isbnlib-mcues: https://pypi.org/project/isbnlib-mcues/

.. _isbnlib-dnb: https://pypi.org/project/isbnlib-dnb/

.. _isbnlib-sbn: https://pypi.org/project/isbnlib-sbn/

.. _isbnlib-kb: https://pypi.org/project/isbnlib-kb/

.. _pypi: https://pypi.python.org/pypi?%3Aaction=search&term=isbnlib_&submit=search
