| Name | pytimeline JSON |
| Version |
0.3.0
JSON |
| download |
| home_page | None |
| Summary | A library for creating clean SVG timelines from JSON. |
| upload_time | 2024-07-31 08:00:35 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.9 |
| license | None |
| keywords |
generator
svg
timeline
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
<h1 align="center">
<b>Pytimeline</b>
</h1>
`pytimeline` is a command line tool for the creation of SVG timelines from JSON.
<p align="center">
<img alt="Simple example" src="examples/timeline.png">
</p>
> [!NOTE]
> This is a rewrite of the old [timeline script](https://github.com/jasonreisman/Timeline)
> from Jason Reisman and full credits go to him for most of the work. I have merely cleaned
> it up and made it into a package with a command line interface.
## Install
The package is compatible with `Python 3.9+` and can be installed in your current environment with `pip`:
```bash
python -m pip install pytimeline
```
## Usage
When the package is installed in your activated environment, it can be called through `python -m pytimeline`.
Detailed usage goes as follows:
```bash
Usage: python -m pytimeline [OPTIONS]
Options:
--inputfile PATH Path to the input JSON file with the
timeline data. [required]
--outputfile PATH Path at which to write the output SVG file.
[default: timeline.svg]
--logging [trace|debug|info|warning|error|critical]
Sets the logging level. [default: info]
--help Show this message and exit.
```
The script will parse your input file and export the `SVG` document in the provided output folder or, if not provided, in the same directory as the input file.
One can otherwise import the high-level object from the package and use it directly:
```python
from pytimeline import Timeline
timeline = Timeline(inputfile="your_input.json")
timeline.build()
timeline.save("timeline.svg")
```
## Input Data Format
The input file is a `JSON` document that describes the start and end points of the timeline, tickmarks along the main axis, as well as callouts to specifc dates/times, and eras which highlight temporal periods.
All date fields can be described in several common date formats and may optionally also include a time of day (e.g. "3/14/15 9:26am").
Datetime parsing is handled by the `pendulum` package, and one can find all the accepted date formats [in the relevant documentation](https://pendulum.eustace.io/docs/#parsing).
### Required and Optional Fields
The required fields are `width`, `start`, and `end`.
All other fields are optional.
**Required:**
* `width` describes the width, in pixels, of the output SVG document, and the height will be determined automatically.
* `start` is the date/time of the leftmost date/time on the axis.
* `end` is the date/time of the rightmost date/time on the axis.
**Optional:**
* `num_ticks` contols the number of tickmarks along the axis between the `start` and `end` date/times (inclusive). If this field is not present, no tickmarks will be generated except for those at the `start` and `end` dates.
* `tick_format` describes the string format of the tickmarks along the axis. See the [valid formats](https://pendulum.eustace.io/docs/#formatter) for the `pendulum` package.
### Special Fields
#### Callouts
Callouts along the axis are described in the `callouts` list, in which each entry is also a list with two to three string values:
* The first value is the `description` of the callout (e.g., "Pi Day"). It is required.
* The second value is the `date/time` of the callout (e.g., "3/14/15 9:26am"). It is required.
* The third value can specify a `color` for the callout, either as a hexcode or a valid SVG color alias. It is optional.
Callout examples:
```JSON
["Ultimate Pi Day", "3/14/15 9:26am"]
```
Or, with a custom callout color:
```JSON
["Ultimate Pi Day", "3/14/15 9:26am", "#CD3F85"]
```
#### Eras
Eras are highlighted temporal periods and are described in the `eras` list.
Like the `callouts` list, each entry in the eras list is itself a list with either three or four string values:
* The first value is the `description` of the era (e.g., "Summer"). It is required.
* The second value is the start `date/time` of the era (e.g., "6/21/15 12am"). It is required.
* The third value is the end `date/time` of the era (e.g. "9/20/15 11:59pm"). It is required.
* The fourth value can specify a `color` for the era, either as a hexcode or a valid SVG color alias. It is optional.
Era examples:
```JSON
["Summer 2015", "6/21/15 12am", "9/20/15 11:59pm"]
```
Or, with a custom era color:
```JSON
["Summer 2015", "6/21/15 12am", "9/20/15 11:59pm", "Orange"]
```
## Simple Example
The `JSON` input for the example timeline at the top of this `README` is:
```json
{
"width" : 750,
"start" : "Oct 8 2015",
"end" : "Oct 15 2015",
"num_ticks" : 14,
"tick_format" : "%b %d, %Y - %I:%M%p",
"callouts" : [
["ABC easy as 123", "Oct 14, 2015 3pm"],
["Midnight Event A", "12am Oct 10, 2015", "#DD0000"],
["Noon Event A", "12pm Oct 10, 2015"],
["5pm Event A", "5pm Oct 10, 2015"],
["Something amazing happening", "Oct 11, 2015"],
["Awesome Event B", "Oct 12, 2015", "#DD0000"],
["C", "Oct 13, 2015"],
["Event E", "Oct 14, 2015"]
],
"eras" : [
["Era 1", "12pm Oct 8, 2015", "3am Oct 12, 2015", "#CD3F85"],
["Era 2", "8am Oct 12, 2015", "12am Oct 15, 2015", "#C0C0FF"]
]
}
```
Raw data
{
"_id": null,
"home_page": null,
"name": "pytimeline",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "Generator, SVG, Timeline",
"author": null,
"author_email": "Felix Soubelet <felix.soubelet@cern.ch>",
"download_url": "https://files.pythonhosted.org/packages/cb/9b/cd3aa11541891626d914a42a87a266e91c8aae1021313834c984bf38407d/pytimeline-0.3.0.tar.gz",
"platform": null,
"description": "<h1 align=\"center\">\n <b>Pytimeline</b>\n</h1>\n\n`pytimeline` is a command line tool for the creation of SVG timelines from JSON.\n\n<p align=\"center\">\n <img alt=\"Simple example\" src=\"examples/timeline.png\">\n</p>\n\n\n> [!NOTE]\n> This is a rewrite of the old [timeline script](https://github.com/jasonreisman/Timeline)\n> from Jason Reisman and full credits go to him for most of the work. I have merely cleaned\n> it up and made it into a package with a command line interface.\n\n## Install\n\nThe package is compatible with `Python 3.9+` and can be installed in your current environment with `pip`:\n\n```bash\npython -m pip install pytimeline\n```\n\n## Usage\n\nWhen the package is installed in your activated environment, it can be called through `python -m pytimeline`.\nDetailed usage goes as follows:\n\n```bash\nUsage: python -m pytimeline [OPTIONS]\n\nOptions:\n --inputfile PATH Path to the input JSON file with the\n timeline data. [required]\n --outputfile PATH Path at which to write the output SVG file.\n [default: timeline.svg]\n --logging [trace|debug|info|warning|error|critical]\n Sets the logging level. [default: info]\n --help Show this message and exit.\n```\n\nThe script will parse your input file and export the `SVG` document in the provided output folder or, if not provided, in the same directory as the input file.\n\nOne can otherwise import the high-level object from the package and use it directly:\n\n```python\nfrom pytimeline import Timeline\n\ntimeline = Timeline(inputfile=\"your_input.json\")\ntimeline.build()\ntimeline.save(\"timeline.svg\")\n```\n\n## Input Data Format\n\nThe input file is a `JSON` document that describes the start and end points of the timeline, tickmarks along the main axis, as well as callouts to specifc dates/times, and eras which highlight temporal periods.\n\nAll date fields can be described in several common date formats and may optionally also include a time of day (e.g. \"3/14/15 9:26am\").\nDatetime parsing is handled by the `pendulum` package, and one can find all the accepted date formats [in the relevant documentation](https://pendulum.eustace.io/docs/#parsing).\n\n### Required and Optional Fields\n\nThe required fields are `width`, `start`, and `end`. \nAll other fields are optional. \n\n**Required:**\n\n* `width` describes the width, in pixels, of the output SVG document, and the height will be determined automatically.\n* `start` is the date/time of the leftmost date/time on the axis.\n* `end` is the date/time of the rightmost date/time on the axis.\n\n**Optional:**\n\n* `num_ticks` contols the number of tickmarks along the axis between the `start` and `end` date/times (inclusive). If this field is not present, no tickmarks will be generated except for those at the `start` and `end` dates.\n* `tick_format` describes the string format of the tickmarks along the axis. See the [valid formats](https://pendulum.eustace.io/docs/#formatter) for the `pendulum` package.\n\n### Special Fields\n\n#### Callouts\n\nCallouts along the axis are described in the `callouts` list, in which each entry is also a list with two to three string values:\n\n* The first value is the `description` of the callout (e.g., \"Pi Day\"). It is required.\n* The second value is the `date/time` of the callout (e.g., \"3/14/15 9:26am\"). It is required.\n* The third value can specify a `color` for the callout, either as a hexcode or a valid SVG color alias. It is optional.\n\nCallout examples:\n\n```JSON\n[\"Ultimate Pi Day\", \"3/14/15 9:26am\"]\n```\n\nOr, with a custom callout color:\n\n```JSON\n[\"Ultimate Pi Day\", \"3/14/15 9:26am\", \"#CD3F85\"]\n```\n\n#### Eras\n\nEras are highlighted temporal periods and are described in the `eras` list.\nLike the `callouts` list, each entry in the eras list is itself a list with either three or four string values:\n\n* The first value is the `description` of the era (e.g., \"Summer\"). It is required.\n* The second value is the start `date/time` of the era (e.g., \"6/21/15 12am\"). It is required.\n* The third value is the end `date/time` of the era (e.g. \"9/20/15 11:59pm\"). It is required.\n* The fourth value can specify a `color` for the era, either as a hexcode or a valid SVG color alias. It is optional.\n\nEra examples:\n\n```JSON\n[\"Summer 2015\", \"6/21/15 12am\", \"9/20/15 11:59pm\"]\n```\n\nOr, with a custom era color:\n\n```JSON\n[\"Summer 2015\", \"6/21/15 12am\", \"9/20/15 11:59pm\", \"Orange\"]\n```\n\n## Simple Example\n\nThe `JSON` input for the example timeline at the top of this `README` is:\n\n```json\n{\n \"width\" : 750,\n \"start\" : \"Oct 8 2015\",\n \"end\" : \"Oct 15 2015\",\n \"num_ticks\" : 14,\n \"tick_format\" : \"%b %d, %Y - %I:%M%p\",\n \"callouts\" : [\n [\"ABC easy as 123\", \"Oct 14, 2015 3pm\"],\n [\"Midnight Event A\", \"12am Oct 10, 2015\", \"#DD0000\"],\n [\"Noon Event A\", \"12pm Oct 10, 2015\"],\n [\"5pm Event A\", \"5pm Oct 10, 2015\"],\n [\"Something amazing happening\", \"Oct 11, 2015\"],\n [\"Awesome Event B\", \"Oct 12, 2015\", \"#DD0000\"],\n [\"C\", \"Oct 13, 2015\"],\n [\"Event E\", \"Oct 14, 2015\"]\n ],\n \"eras\" : [\n [\"Era 1\", \"12pm Oct 8, 2015\", \"3am Oct 12, 2015\", \"#CD3F85\"],\n [\"Era 2\", \"8am Oct 12, 2015\", \"12am Oct 15, 2015\", \"#C0C0FF\"]\n ]\n}\n```\n",
"bugtrack_url": null,
"license": null,
"summary": "A library for creating clean SVG timelines from JSON.",
"version": "0.3.0",
"project_urls": {
"homepage": "https://github.com/fsoubelet/Timeline",
"repository": "https://github.com/fsoubelet/Timeline"
},
"split_keywords": [
"generator",
" svg",
" timeline"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "d3bcb0501d73509e52dda698eece64ab00a57fed72e8d9a75d929dda94748a2b",
"md5": "c26858f636fbea640f4610d9f7d071ea",
"sha256": "c84d6046b9735bcc940c1148c7fe34bcffde79bf382b3a40c88f43075825d0b2"
},
"downloads": -1,
"filename": "pytimeline-0.3.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "c26858f636fbea640f4610d9f7d071ea",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 9598,
"upload_time": "2024-07-31T08:00:37",
"upload_time_iso_8601": "2024-07-31T08:00:37.211157Z",
"url": "https://files.pythonhosted.org/packages/d3/bc/b0501d73509e52dda698eece64ab00a57fed72e8d9a75d929dda94748a2b/pytimeline-0.3.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "cb9bcd3aa11541891626d914a42a87a266e91c8aae1021313834c984bf38407d",
"md5": "49a445fa332bbdbd0a42629d83f425e2",
"sha256": "3d48bc86edca9c31e0100a1f833a6760b1b7c57d04e0b20659c21491c79fce30"
},
"downloads": -1,
"filename": "pytimeline-0.3.0.tar.gz",
"has_sig": false,
"md5_digest": "49a445fa332bbdbd0a42629d83f425e2",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 208433,
"upload_time": "2024-07-31T08:00:35",
"upload_time_iso_8601": "2024-07-31T08:00:35.307989Z",
"url": "https://files.pythonhosted.org/packages/cb/9b/cd3aa11541891626d914a42a87a266e91c8aae1021313834c984bf38407d/pytimeline-0.3.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-07-31 08:00:35",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "fsoubelet",
"github_project": "Timeline",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "pytimeline"
}
