# kroki
Access [kroki](https://kroki.io/) from python.
To install: ```pip install kroki```
Read the overview below, or
view/download/play [this demo notebook](https://github.com/thorwhalen/kroki/blob/main/misc/kroki%20demo.ipynb)
to see how to use this package.
The `kroki` python package is a convenience package for you to be able to generate diagrams,
through [kroki](https://kroki.io/), getting your images as bytes or as ipython objects via python
functions or doing some "cell magic" in your jupyter notebooks.
I suggest you have a look at the [kroki's excellent homepage](https://kroki.io/)
where you'll be able to try different diagram types out.
Don't miss the nice [cheatsheet](https://kroki.io/assets/kroki_cheatsheet_20210515_v1.1_EN.pdf) there.
# Overview
You can get the bytes of an image of a diagram like so:
```python
from kroki import diagram_image_bytes
svn_bytes = diagram_image_bytes('Bob->Alice : Hello!')
# which you can then save in a file...
```
When in a jupyter notebook though, you have a more convenient function that will put those bytes into an IPython display object, which you can then display (will automatically call display if it's the last command of the cell), amongst other things.
```python
from kroki import diagram_image
diagram_image('Bob->Alice : Hello!')
```
<img width="123" alt="image" src="https://user-images.githubusercontent.com/1906276/211854316-501ec323-bd26-4428-a722-2fa200bfbea3.png">
In both those functions, the default is `diagram_type='plantuml'` and `output_format='svg'`.
But you have other choices.
```python
diagram_image('digraph D {Alice -> Bob, Charles -> Darwin}', diagram_type='graphviz')
```
<img width="240" alt="image" src="https://user-images.githubusercontent.com/1906276/212101184-376b2565-c241-4bcb-81f9-50c1eb538675.png">
```python
png_bytes = diagram_image_bytes('Bob->Alice : Hello!', output_format='png')
png_bytes[:7]
```
b'\x89PNG\r\n\x1a'
And then, there's magic, which will allow you to write your diagram source directly in a notebook's cell.
```python
%load_ext kroki
```
```python
%%kroki
Bob->Alice : Hello!
```
<img width="123" alt="image" src="https://user-images.githubusercontent.com/1906276/211854316-501ec323-bd26-4428-a722-2fa200bfbea3.png">
The default `diagram_type` is still `plantuml`, but you can specify another type if you want.
```python
%%kroki graphviz
digraph D {
Alice -> Bob, Charles -> Darwin
}
```
<img width="240" alt="image" src="https://user-images.githubusercontent.com/1906276/212101184-376b2565-c241-4bcb-81f9-50c1eb538675.png">
To see what diagram types `kroki` supports through the `diagram_types` variable.
```python
from kroki import diagram_types
print(diagram_types)
```
{'svgbob', 'vega', 'packetdiag', 'mermaid', 'structurizr', 'bytefield', 'vegalite', 'c4plantuml', 'pikchr', 'rackdiag', 'ditaa', 'wavedrom', 'nwdiag', 'graphviz', 'excalidraw', 'plantuml', 'erd', 'umlet', 'actdiag', 'nomnoml', 'bpmn', 'seqdiag', 'blockdiag'}
Not all `output_format` values are supported for all diagram types. To which are supported for which types, you can have a look at the `output_formats` dictionary, which which contains both the choices of diagram_type (as keys) and the corresponding output_format each support (as values).
```python
from kroki import output_formats
output_formats['plantuml']
```
['png', 'svg', 'jpeg', 'base64']
```python
output_formats['mermaid']
```
['svg']
```python
output_formats['seqdiag']
```
['png', 'svg', 'pdf']
# Misc
The `kroki` function is just an alias of `diagram_image` which itself, is the composition of `diagram_image_bytes` and `bytes_to_image` to get an iPython image object as your output (which results in displaying the image when it's the last command of your cell).
The default `diagram_type` of `diagram_image` is `plantuml`.
We also made some ready-to-use `mermaid_image` and `graphviz_image` by fixing `diagram_type` with `functools.partial`.
```python
diagram_image = wrap(diagram_image_bytes, egress=bytes_to_image)
mermaid_image = wrap(
partial(diagram_image_bytes, diagram_type='mermaid'), egress=bytes_to_image
)
graphviz_image = wrap(
partial(diagram_image_bytes, diagram_type='graphviz'), egress=bytes_to_image
)
kroki = diagram_image # alias
```
You can import these directory from `kroki`.
Raw data
{
"_id": null,
"home_page": "https://github.com/thorwhalen/kroki",
"name": "kroki",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": null,
"author": "Thor Whalen",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/c9/40/aa26d4c710c7c88e6cb2d6da39cdeac32b1b0e019b1d704b004f0f5f97de/kroki-0.1.2.tar.gz",
"platform": "any",
"description": "# kroki\n\nAccess [kroki](https://kroki.io/) from python. \n\nTo install:\t```pip install kroki```\n\nRead the overview below, or\nview/download/play [this demo notebook](https://github.com/thorwhalen/kroki/blob/main/misc/kroki%20demo.ipynb) \nto see how to use this package.\n\nThe `kroki` python package is a convenience package for you to be able to generate diagrams, \nthrough [kroki](https://kroki.io/), getting your images as bytes or as ipython objects via python \nfunctions or doing some \"cell magic\" in your jupyter notebooks.\n\nI suggest you have a look at the [kroki's excellent homepage](https://kroki.io/) \nwhere you'll be able to try different diagram types out. \nDon't miss the nice [cheatsheet](https://kroki.io/assets/kroki_cheatsheet_20210515_v1.1_EN.pdf) there.\n\n\n# Overview\n\nYou can get the bytes of an image of a diagram like so:\n\n```python\nfrom kroki import diagram_image_bytes\n\nsvn_bytes = diagram_image_bytes('Bob->Alice : Hello!')\n# which you can then save in a file...\n```\n\nWhen in a jupyter notebook though, you have a more convenient function that will put those bytes into an IPython display object, which you can then display (will automatically call display if it's the last command of the cell), amongst other things.\n\n\n```python\nfrom kroki import diagram_image\n\ndiagram_image('Bob->Alice : Hello!')\n```\n\n<img width=\"123\" alt=\"image\" src=\"https://user-images.githubusercontent.com/1906276/211854316-501ec323-bd26-4428-a722-2fa200bfbea3.png\">\n\n\nIn both those functions, the default is `diagram_type='plantuml'` and `output_format='svg'`.\n\nBut you have other choices.\n\n\n```python\ndiagram_image('digraph D {Alice -> Bob, Charles -> Darwin}', diagram_type='graphviz')\n```\n\n<img width=\"240\" alt=\"image\" src=\"https://user-images.githubusercontent.com/1906276/212101184-376b2565-c241-4bcb-81f9-50c1eb538675.png\">\n\n\n```python\npng_bytes = diagram_image_bytes('Bob->Alice : Hello!', output_format='png')\npng_bytes[:7]\n```\n\n\n b'\\x89PNG\\r\\n\\x1a'\n\n\nAnd then, there's magic, which will allow you to write your diagram source directly in a notebook's cell.\n\n\n```python\n%load_ext kroki\n```\n\n\n```python\n%%kroki\n\nBob->Alice : Hello!\n```\n\n<img width=\"123\" alt=\"image\" src=\"https://user-images.githubusercontent.com/1906276/211854316-501ec323-bd26-4428-a722-2fa200bfbea3.png\">\n\n\nThe default `diagram_type` is still `plantuml`, but you can specify another type if you want.\n\n\n```python\n%%kroki graphviz\n\ndigraph D {\n Alice -> Bob, Charles -> Darwin\n}\n```\n\n<img width=\"240\" alt=\"image\" src=\"https://user-images.githubusercontent.com/1906276/212101184-376b2565-c241-4bcb-81f9-50c1eb538675.png\">\n\n\nTo see what diagram types `kroki` supports through the `diagram_types` variable.\n\n\n```python\nfrom kroki import diagram_types\n\nprint(diagram_types)\n```\n\n {'svgbob', 'vega', 'packetdiag', 'mermaid', 'structurizr', 'bytefield', 'vegalite', 'c4plantuml', 'pikchr', 'rackdiag', 'ditaa', 'wavedrom', 'nwdiag', 'graphviz', 'excalidraw', 'plantuml', 'erd', 'umlet', 'actdiag', 'nomnoml', 'bpmn', 'seqdiag', 'blockdiag'}\n\n\nNot all `output_format` values are supported for all diagram types. To which are supported for which types, you can have a look at the `output_formats` dictionary, which which contains both the choices of diagram_type (as keys) and the corresponding output_format each support (as values).\n\n\n```python\nfrom kroki import output_formats\n\noutput_formats['plantuml']\n```\n\n\n ['png', 'svg', 'jpeg', 'base64']\n\n\n```python\noutput_formats['mermaid']\n```\n\n\n\n ['svg']\n\n\n\n\n```python\noutput_formats['seqdiag']\n```\n\n\n ['png', 'svg', 'pdf']\n\n\n\n# Misc\n\nThe `kroki` function is just an alias of `diagram_image` which itself, is the composition of `diagram_image_bytes` and `bytes_to_image` to get an iPython image object as your output (which results in displaying the image when it's the last command of your cell). \n\nThe default `diagram_type` of `diagram_image` is `plantuml`. \nWe also made some ready-to-use `mermaid_image` and `graphviz_image` by fixing `diagram_type` with `functools.partial`. \n\n```python\ndiagram_image = wrap(diagram_image_bytes, egress=bytes_to_image)\nmermaid_image = wrap(\n partial(diagram_image_bytes, diagram_type='mermaid'), egress=bytes_to_image\n)\ngraphviz_image = wrap(\n partial(diagram_image_bytes, diagram_type='graphviz'), egress=bytes_to_image\n)\nkroki = diagram_image # alias\n```\n\nYou can import these directory from `kroki`.",
"bugtrack_url": null,
"license": "apache-2.0",
"summary": "Access kroki from python",
"version": "0.1.2",
"project_urls": {
"Homepage": "https://github.com/thorwhalen/kroki"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "c940aa26d4c710c7c88e6cb2d6da39cdeac32b1b0e019b1d704b004f0f5f97de",
"md5": "0850435bb6eefa0318fb408d6cb8a857",
"sha256": "f5c03aa61f0a27c81d435b53cd817d2202a0a44ae084c42129adcdeaa2c4c40f"
},
"downloads": -1,
"filename": "kroki-0.1.2.tar.gz",
"has_sig": false,
"md5_digest": "0850435bb6eefa0318fb408d6cb8a857",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 8776,
"upload_time": "2024-07-07T13:03:43",
"upload_time_iso_8601": "2024-07-07T13:03:43.124969Z",
"url": "https://files.pythonhosted.org/packages/c9/40/aa26d4c710c7c88e6cb2d6da39cdeac32b1b0e019b1d704b004f0f5f97de/kroki-0.1.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-07-07 13:03:43",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "thorwhalen",
"github_project": "kroki",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "kroki"
}
JSON
