Python library and assorted tools for assisting with the Mongoose
Traveller TTRPG system.
The extracted data is **not** for redistribution, as it is almost
certainly subject to copyright (I am not a lawyer - but it’s safer to
assume caution over distribution). This utility (and its output) is
intended as an aid to those who legally own a copy of the Mongoose
Traveller materials, and wish to make use of the data for their own
direct purposes. It is the sole responsibility of the user of this
program to use the extracted data in a manner that respects the
publisher’s IP rights.
.. important::
Do not distribute the data extracted PDF files without explicit
permission from the copyright holder.
The purpose of this tool is to extract the data for usage by the legal
owner of a copy of the original materal that it was extracted from.
.. _`_reporting_issues`:
Reporting issues
================
Report any problems you encounter or feature requests to
https://github.com/huin/travdata/issues.
Please include:
- information about which operating system you are using the program
on,
- steps to reproduce the problem,
- what you expected to happen,
- what actually happened.
Ideally include text output of any error messages from the program,
and/or screenshots to demonstrate the problem if text output is not
relevant.
.. _`_usage`:
Usage
=====
This package is primarily intended for the provided CLI tools, but API
access is also possible.
.. _`_requirements`:
Requirements
============
Java Runtime Environment (JRE) must be installed. This is required by
the code that extracts tables from PDFs. If not already installed, get
it from `java.com <https://www.java.com/en/download/>`__.
.. _`_installation`:
Installation
------------
.. _`_prebuilt`:
Prebuilt
~~~~~~~~
You can download an executable version of the application for your
platform at
`github.com/huin/travdata/releases <https://github.com/huin/travdata/releases>`__.
Currently executables are only generated for Linux and Windows, and seem
to work on the author’s machines. A MacOS binary is also released, but
it has not been tested.
Once downloaded, extract the ``.zip`` file to a suitable location. You
can most easily use the command line interface from the directory that
it was unpacked to.
You may also wish to make a shortcut to the ``travdata_gui`` executable,
but it can also be run directly from the unzipped directory.
.. _`_pip_install`:
Pip install
~~~~~~~~~~~
This may work on platforms that have no prebuilt executable. Assuming
that you have Python 3.11 or later installed, and you are running
something similar to Linux, perform the following commands to install
into a Python virtual environment:
.. code:: console
mkdir travdata
cd travdata
python -m venv venv
source ./venv/bin/activate
You will also need to download a copy of the source code, in order to
get a copy of the configuration. Visit
`releases <https://github.com/huin/travdata/releases>`__, pick a recent
release, and download the "Source code" zip file. Extract the ``config``
directory from it, and place it in the ``travdata`` directory you
created earlier, such that the ``travdata`` directory contains two
subdirectories:
- ``config``
- ``venv``
At this point, you can run ``python -m travdata.cli.cli`` instead of
running ``travdata_cli`` from other examples.
.. _`_gui_literal_travdata_gui_literal`:
GUI ``travdata_gui``
--------------------
The GUI binary provides a user interface to aid in extracting CSV files,
similarly to ``travdata_cli extractcsvtables``.
.. figure::
https://raw.githubusercontent.com/huin/travdata/main/images/extraction_gui.png
:alt: Screenshot of extraction configuration GUI
1. "Extraction configuration" selects the configuration for extraction
from PDFs. It should detect its own configuration automatically. If
it does not, click "Select configuration" and select the
``_internal/config`` directory that should have come with the
download of the program.
2. "Input PDF" selects the PDF to extract from, and the book that that
PDF corresponds to.
Note: only a very limited number of books are supported - at the time
of writing, only the Core Rulebook 2022 update.
Click "Select PDF" and choose the input PDF file.
3. If selecting a PDF file did not automatically choose the correct book
(based on its filename), choose it from the drop-down box below
"Select PDF".
4. "Output directory" selects a directory to write the extracted CSV
data into. Choose an empty directory.
5. "Extract" should now be enabled. Click it to start extraction. It
will open a window to display progress and any errors.
6. Close the extraction window once extraction is completed (and if you
no longer need the output).
Note: the program will not extract the same table again if it sees that
the CSV file is present in the output directory. If you wish to force
re-extraction, delete some or all files from the output directory.
.. _`_cli_literal_travdata_cli_extractcsvtables_literal`:
CLI ``travdata_cli extractcsvtables``
-------------------------------------
This tool extracts CSV files from tables in the given PDF, based on the
given configuration files that specifies the specifics of how those
tables can be turned into useful CSV data. As such, it only supports
extraction of tables from known PDF files, where the individual tables
have been configured.
The general form of the command is:
.. code:: shell
travdata_cli extractcsvtables BOOK_NAME INPUT.PDF OUT_DIR
Where:
``BOOK_NAME``
is the identifier for the book to extract tables from. This selects
the correct book’s configuration from the files that . Use
``travdata_cli listbooks`` to list accepted values for this argument.
``INPUT.PDF``
is the path to the PDF file to read tables from.
``OUT_DIR``
is the path to a (potentially not existing) directory to output the
resulting CSV files. This will result in containing a directory and
file structure that mirrors that in ``CONFIG_DIR``, but will contain
``.csv`` rather than ``.tabula-template.json`` files.
At the present time, the only supported input PDF file is the Mongoose
Traveller Core Rulebook 2022, and not all tables are yet supported for
extraction.
Example:
.. code:: shell
travdata_cli extractcsvtables \
core_rulebook_2022 path/to/update_2022_core_rulebook.pdf \
path_to_output_dir
.. _`_developing`:
Developing
==========
See
```development.adoc`` <https://github.com/huin/travdata/blob/main/development.adoc>`__
for more information on developing and adding more tables to the
configuration.
Raw data
{
"_id": null,
"home_page": "https://github.com/huin/travdata",
"name": "travdata",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.11",
"maintainer_email": null,
"keywords": "traveller, ttrpg",
"author": "John Beisley",
"author_email": "johnbeisleyuk@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/33/d7/8ab032a721f11072587a0a7ae85192183520042f3172a92c58e7bc6f2d4e/travdata-0.4.1.tar.gz",
"platform": null,
"description": "Python library and assorted tools for assisting with the Mongoose\nTraveller TTRPG system.\n\nThe extracted data is **not** for redistribution, as it is almost\ncertainly subject to copyright (I am not a lawyer - but it\u2019s safer to\nassume caution over distribution). This utility (and its output) is\nintended as an aid to those who legally own a copy of the Mongoose\nTraveller materials, and wish to make use of the data for their own\ndirect purposes. It is the sole responsibility of the user of this\nprogram to use the extracted data in a manner that respects the\npublisher\u2019s IP rights.\n\n.. important::\n\n Do not distribute the data extracted PDF files without explicit\n permission from the copyright holder.\n\nThe purpose of this tool is to extract the data for usage by the legal\nowner of a copy of the original materal that it was extracted from.\n\n.. _`_reporting_issues`:\n\nReporting issues\n================\n\nReport any problems you encounter or feature requests to\nhttps://github.com/huin/travdata/issues.\n\nPlease include:\n\n- information about which operating system you are using the program\n on,\n\n- steps to reproduce the problem,\n\n- what you expected to happen,\n\n- what actually happened.\n\nIdeally include text output of any error messages from the program,\nand/or screenshots to demonstrate the problem if text output is not\nrelevant.\n\n.. _`_usage`:\n\nUsage\n=====\n\nThis package is primarily intended for the provided CLI tools, but API\naccess is also possible.\n\n.. _`_requirements`:\n\nRequirements\n============\n\nJava Runtime Environment (JRE) must be installed. This is required by\nthe code that extracts tables from PDFs. If not already installed, get\nit from `java.com <https://www.java.com/en/download/>`__.\n\n.. _`_installation`:\n\nInstallation\n------------\n\n.. _`_prebuilt`:\n\nPrebuilt\n~~~~~~~~\n\nYou can download an executable version of the application for your\nplatform at\n`github.com/huin/travdata/releases <https://github.com/huin/travdata/releases>`__.\nCurrently executables are only generated for Linux and Windows, and seem\nto work on the author\u2019s machines. A MacOS binary is also released, but\nit has not been tested.\n\nOnce downloaded, extract the ``.zip`` file to a suitable location. You\ncan most easily use the command line interface from the directory that\nit was unpacked to.\n\nYou may also wish to make a shortcut to the ``travdata_gui`` executable,\nbut it can also be run directly from the unzipped directory.\n\n.. _`_pip_install`:\n\nPip install\n~~~~~~~~~~~\n\nThis may work on platforms that have no prebuilt executable. Assuming\nthat you have Python 3.11 or later installed, and you are running\nsomething similar to Linux, perform the following commands to install\ninto a Python virtual environment:\n\n.. code:: console\n\n mkdir travdata\n cd travdata\n python -m venv venv\n source ./venv/bin/activate\n\nYou will also need to download a copy of the source code, in order to\nget a copy of the configuration. Visit\n`releases <https://github.com/huin/travdata/releases>`__, pick a recent\nrelease, and download the \"Source code\" zip file. Extract the ``config``\ndirectory from it, and place it in the ``travdata`` directory you\ncreated earlier, such that the ``travdata`` directory contains two\nsubdirectories:\n\n- ``config``\n\n- ``venv``\n\nAt this point, you can run ``python -m travdata.cli.cli`` instead of\nrunning ``travdata_cli`` from other examples.\n\n.. _`_gui_literal_travdata_gui_literal`:\n\nGUI ``travdata_gui``\n--------------------\n\nThe GUI binary provides a user interface to aid in extracting CSV files,\nsimilarly to ``travdata_cli extractcsvtables``.\n\n.. figure::\n https://raw.githubusercontent.com/huin/travdata/main/images/extraction_gui.png\n :alt: Screenshot of extraction configuration GUI\n\n1. \"Extraction configuration\" selects the configuration for extraction\n from PDFs. It should detect its own configuration automatically. If\n it does not, click \"Select configuration\" and select the\n ``_internal/config`` directory that should have come with the\n download of the program.\n\n2. \"Input PDF\" selects the PDF to extract from, and the book that that\n PDF corresponds to.\n\n Note: only a very limited number of books are supported - at the time\n of writing, only the Core Rulebook 2022 update.\n\n Click \"Select PDF\" and choose the input PDF file.\n\n3. If selecting a PDF file did not automatically choose the correct book\n (based on its filename), choose it from the drop-down box below\n \"Select PDF\".\n\n4. \"Output directory\" selects a directory to write the extracted CSV\n data into. Choose an empty directory.\n\n5. \"Extract\" should now be enabled. Click it to start extraction. It\n will open a window to display progress and any errors.\n\n6. Close the extraction window once extraction is completed (and if you\n no longer need the output).\n\nNote: the program will not extract the same table again if it sees that\nthe CSV file is present in the output directory. If you wish to force\nre-extraction, delete some or all files from the output directory.\n\n.. _`_cli_literal_travdata_cli_extractcsvtables_literal`:\n\nCLI ``travdata_cli extractcsvtables``\n-------------------------------------\n\nThis tool extracts CSV files from tables in the given PDF, based on the\ngiven configuration files that specifies the specifics of how those\ntables can be turned into useful CSV data. As such, it only supports\nextraction of tables from known PDF files, where the individual tables\nhave been configured.\n\nThe general form of the command is:\n\n.. code:: shell\n\n travdata_cli extractcsvtables BOOK_NAME INPUT.PDF OUT_DIR\n\nWhere:\n\n``BOOK_NAME``\n is the identifier for the book to extract tables from. This selects\n the correct book\u2019s configuration from the files that . Use\n ``travdata_cli listbooks`` to list accepted values for this argument.\n\n``INPUT.PDF``\n is the path to the PDF file to read tables from.\n\n``OUT_DIR``\n is the path to a (potentially not existing) directory to output the\n resulting CSV files. This will result in containing a directory and\n file structure that mirrors that in ``CONFIG_DIR``, but will contain\n ``.csv`` rather than ``.tabula-template.json`` files.\n\nAt the present time, the only supported input PDF file is the Mongoose\nTraveller Core Rulebook 2022, and not all tables are yet supported for\nextraction.\n\nExample:\n\n.. code:: shell\n\n travdata_cli extractcsvtables \\\n core_rulebook_2022 path/to/update_2022_core_rulebook.pdf \\\n path_to_output_dir\n\n.. _`_developing`:\n\nDeveloping\n==========\n\nSee\n```development.adoc`` <https://github.com/huin/travdata/blob/main/development.adoc>`__\nfor more information on developing and adding more tables to the\nconfiguration.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Data utility code for Mongoose Traveller TTRPG.",
"version": "0.4.1",
"project_urls": {
"Homepage": "https://github.com/huin/travdata",
"Issues": "https://github.com/huin/travdata/issues",
"Repository": "https://github.com/huin/travdata"
},
"split_keywords": [
"traveller",
" ttrpg"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "991dbdff6fed19d45be99b75473eac1cb9f0c5fb8cf7c4ce058527bbc71ccdbe",
"md5": "d9dac7fdc4548fa9aaa5202147382c7e",
"sha256": "90945e4f3fe7d9813b0e3da477d424a754c34abf775d281fc078304c4ceef6f1"
},
"downloads": -1,
"filename": "travdata-0.4.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "d9dac7fdc4548fa9aaa5202147382c7e",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.11",
"size": 58707,
"upload_time": "2024-05-04T07:31:22",
"upload_time_iso_8601": "2024-05-04T07:31:22.524258Z",
"url": "https://files.pythonhosted.org/packages/99/1d/bdff6fed19d45be99b75473eac1cb9f0c5fb8cf7c4ce058527bbc71ccdbe/travdata-0.4.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "33d78ab032a721f11072587a0a7ae85192183520042f3172a92c58e7bc6f2d4e",
"md5": "848ffc7e78b48c7521cc4983f8b09b24",
"sha256": "7039ba4dd6ec43cf1a02bd1086e3f7d32814e4e8a4b0a99be2206c74857f6446"
},
"downloads": -1,
"filename": "travdata-0.4.1.tar.gz",
"has_sig": false,
"md5_digest": "848ffc7e78b48c7521cc4983f8b09b24",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.11",
"size": 46337,
"upload_time": "2024-05-04T07:31:24",
"upload_time_iso_8601": "2024-05-04T07:31:24.365199Z",
"url": "https://files.pythonhosted.org/packages/33/d7/8ab032a721f11072587a0a7ae85192183520042f3172a92c58e7bc6f2d4e/travdata-0.4.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-05-04 07:31:24",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "huin",
"github_project": "travdata",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "travdata"
}
JSON
