PyDIVKit examples
=================
This library is designed to work with [DivKit](http://divkit.tech/) with python.
Features:
* Declarative and imperative DivKit blocks definition
* Native Type-hints support
* Complete object-oriented API
* IDE type checks and suggestions
Object construction
-------------------
The main idea is to provide a tool for creating blocks using Python objects.
```python
import json
import pydivkit as dk
container = dk.DivContainer(
items=[
dk.DivGallery(
items=[
dk.DivText(text="Hello from pydivkit")
]
)
]
)
print(json.dumps(container.dict(), indent=1))
# {
# "type": "container",
# "items": [
# {
# "type": "gallery",
# "items": [
# {
# "type": "text",
# "text": "Hello from pydivkit"
# }
# ]
# }
# ]
# }
```
Slider example
--------------
Following code is a rewritten slider example using pydivkit.
```python
import pydivkit as dk
slider = dk.DivData(
log_id="sample_card",
states=[
dk.DivDataState(
state_id=0,
div=dk.DivSlider(
width=dk.DivMatchParentSize(),
max_value=10,
min_value=1,
thumb_style=dk.DivShapeDrawable(
color="#00b300",
stroke=dk.DivStroke(
color="#ffffff",
width=3,
),
shape=dk.DivRoundedRectangleShape(
item_width=dk.DivFixedSize(value=32),
item_height=dk.DivFixedSize(value=32),
corner_radius=dk.DivFixedSize(value=100)
),
),
track_active_style=dk.DivShapeDrawable(
color="#00b300",
shape=dk.DivRoundedRectangleShape(
item_height=dk.DivFixedSize(value=6)
)
),
track_inactive_style=dk.DivShapeDrawable(
color="#20000000",
shape=dk.DivRoundedRectangleShape(
item_height=dk.DivFixedSize(value=6)
)
)
)
)
]
)
```
This example might be serialised like this:
```python
import json
print(json.dumps(slider.dict(), indent=1))
# {
# "log_id": "sample_card",
# "states": [
# {
# "div": {
# "type": "slider",
# "max_value": 10,
# "min_value": 1,
# "thumb_style": {
# "type": "shape_drawable",
# "color": "#00b300",
# "shape": {
# "type": "rounded_rectangle",
# "corner_radius": {
# "type": "fixed",
# "value": 100
# },
# "item_height": {
# "type": "fixed",
# "value": 32
# },
# "item_width": {
# "type": "fixed",
# "value": 32
# }
# },
# "stroke": {
# "color": "#ffffff",
# "width": 3
# }
# },
# "track_active_style": {
# "type": "shape_drawable",
# "color": "#00b300",
# "shape": {
# "type": "rounded_rectangle",
# "item_height": {
# "type": "fixed",
# "value": 6
# }
# }
# },
# "track_inactive_style": {
# "type": "shape_drawable",
# "color": "#20000000",
# "shape": {
# "type": "rounded_rectangle",
# "item_height": {
# "type": "fixed",
# "value": 6
# }
# }
# },
# "width": {
# "type": "match_parent"
# }
# },
# "state_id": 0
# }
# ]
# }
```
Templating and DRY
------------------
Of course, manually building blocks from your code every time is boring.
So, the first idea is to move the initialization of DivKit objects
into functions.
```python
# Naive DRY example which strictly non-recommended
import pydivkit as dk
def get_size(value: int = 32) -> dk.DivFixedSize:
return dk.DivFixedSize(value=value)
def get_shape() -> dk.DivShape:
return dk.DivShape(
item_width=get_size(),
item_height=get_size(),
corner_radius=get_size(100)
)
slider_shape = get_shape()
slider = dk.DivData(
log_id="sample_card",
states=[
dk.DivDataState(
# other arguments
div=dk.DivSlider(
thumb_style=dk.DivShapeDrawable(
shape=slider_shape,
# other arguments
),
# other arguments
)
)
]
)
```
Looks a little better, but this approach doesn't scale well. To simplify layout
and save traffic, DivKit has templates. This is a way to layout similar elements
without having to declare the complete json, but just declare a template and use
this many times in similar items.
**PyDivKit supports defining templates through the inheritance.**
Let's define an example card:
```python
import json
import pydivkit as dk
class CategoriesItem(dk.DivContainer):
"""
Class inherited from dk.DivContainer will have a template
"""
# Special object for mark this fields a DivKit field in template
icon_url: str = dk.Field()
text: str = dk.Field()
# Set defaults layout for in the template
width = dk.DivWrapContentSize()
background = [dk.DivSolidBackground(color="#f0f0f0")]
content_alignment_vertical = dk.DivAlignmentVertical.CENTER
orientation = dk.DivContainerOrientation.HORIZONTAL
paddings = dk.DivEdgeInsets(left=12, right=12, top=10, bottom=10)
border = dk.DivBorder(corner_radius=12)
items = [
dk.DivImage(
width=dk.DivFixedSize(value=20),
height=dk.DivFixedSize(value=20),
margins=dk.DivEdgeInsets(right=6),
# Special object Ref it's a reference for Field property
image_url=dk.Ref(icon_url),
),
dk.DivText(
width=dk.DivWrapContentSize(),
max_lines=1,
# Special object Ref it's a reference for Field property
text=dk.Ref(text),
),
]
BASE_URL = "https://leonardo.edadeal.io/dyn/re/segments/level1/96"
# So after class definition you might use all the `Field` marked property
# names as an argument.
gallery = dk.DivGallery(
items=[
CategoriesItem(
text="Food", icon_url=f"{BASE_URL}/food.png",
),
CategoriesItem(
text="Alcohol", icon_url=f"{BASE_URL}/alcohol.png",
),
CategoriesItem(
text="Household", icon_url=f"{BASE_URL}/household.png",
),
]
)
print(json.dumps(dk.make_div(gallery), indent=1, ensure_ascii=False))
# {
# "templates": {
# "__main__.CategoriesItem": {
# "type": "container",
# "background": [
# {
# "type": "solid",
# "color": "#f0f0f0"
# }
# ],
# "border": {
# "corner_radius": 12
# },
# "content_alignment_vertical": "center",
# "items": [
# {
# "type": "image",
# "height": {
# "type": "fixed",
# "value": 20
# },
# "$image_url": "icon_url",
# "margins": {
# "right": 6
# },
# "width": {
# "type": "fixed",
# "value": 20
# }
# },
# {
# "type": "text",
# "max_lines": 1,
# "$text": "text",
# "width": {
# "type": "wrap_content"
# }
# }
# ],
# "orientation": "horizontal",
# "paddings": {
# "bottom": 10,
# "left": 12,
# "right": 12,
# "top": 10
# },
# "width": {
# "type": "wrap_content"
# }
# }
# },
# "card": {
# "log_id": "card",
# "states": [
# {
# "div": {
# "type": "gallery",
# "items": [
# {
# "type": "__main__.CategoriesItem",
# "icon_url": "https://leonardo.edadeal.io/dyn/re/segments/level1/96/food.png",
# "text": "Food"
# },
# {
# "type": "__main__.CategoriesItem",
# "icon_url": "https://leonardo.edadeal.io/dyn/re/segments/level1/96/alcohol.png",
# "text": "Alcohol"
# },
# {
# "type": "__main__.CategoriesItem",
# "icon_url": "https://leonardo.edadeal.io/dyn/re/segments/level1/96/household.png",
# "text": "Household"
# }
# ]
# },
# "state_id": 0
# }
# ]
# }
# }
```
Template names
--------------
By default, templates are collecting by the metaclass into shared storage when
the class is declaring at import time, and have the
format `{module_name}.{class_name}`.
The following example, sure will not occur in the wild, shows a warning if
suddenly the names of the classes, and hence the templates, conflict.
```python
import pydivkit as dk
class MyTemplate(dk.DivContainer):
width = dk.DivWrapContentSize()
class MyTemplate(dk.DivContainer):
pass
# RuntimeWarning: Template 'test.MyTemplate' already defined in
# <class 'test.MyTemplate'> and will be replaced to <class 'test.MyTemplate'>
```
Also, if you do not want to show the structure of your project to the outside,
or for some reason you need to make the example above clean, you can rename the
template by declaring a special attribute `__template_name__`
```python
import pydivkit as dk
class MyTemplate(dk.DivContainer):
width = dk.DivWrapContentSize()
print(MyTemplate.template_name)
# >>> test.MyTemplate
class MyTemplate(dk.DivContainer):
__template_name__ = "MyTemplate2"
print(MyTemplate.template_name)
# >>> MyTemplate2
```
Raw data
{
"_id": null,
"home_page": "https://github.com/divkit/divkit/tree/main/json-builder/python",
"name": "pydivkit",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.8",
"maintainer_email": null,
"keywords": "divkit, sdk",
"author": "Vladislav Bakaev",
"author_email": "bakaev-vlad@yandex-team.ru",
"download_url": "https://files.pythonhosted.org/packages/fe/18/847bb425f707e7a360f6f1cc14428baed391824158e6a8d38614a8d30d56/pydivkit-32.7.1.tar.gz",
"platform": null,
"description": "PyDIVKit examples\n=================\n\nThis library is designed to work with [DivKit](http://divkit.tech/) with python.\n\nFeatures:\n* Declarative and imperative DivKit blocks definition\n* Native Type-hints support\n* Complete object-oriented API\n* IDE type checks and suggestions\n\nObject construction\n-------------------\n\nThe main idea is to provide a tool for creating blocks using Python objects.\n\n```python\nimport json\nimport pydivkit as dk\n\ncontainer = dk.DivContainer(\n items=[\n dk.DivGallery(\n items=[\n dk.DivText(text=\"Hello from pydivkit\")\n ]\n )\n ]\n)\n\nprint(json.dumps(container.dict(), indent=1))\n# {\n# \"type\": \"container\",\n# \"items\": [\n# {\n# \"type\": \"gallery\",\n# \"items\": [\n# {\n# \"type\": \"text\",\n# \"text\": \"Hello from pydivkit\"\n# }\n# ]\n# }\n# ]\n# }\n```\n\nSlider example\n--------------\n\nFollowing code is a rewritten slider example using pydivkit.\n\n```python\nimport pydivkit as dk\n\n\nslider = dk.DivData(\n log_id=\"sample_card\",\n states=[\n dk.DivDataState(\n state_id=0,\n div=dk.DivSlider(\n width=dk.DivMatchParentSize(),\n max_value=10,\n min_value=1,\n thumb_style=dk.DivShapeDrawable(\n color=\"#00b300\",\n stroke=dk.DivStroke(\n color=\"#ffffff\",\n width=3,\n ),\n shape=dk.DivRoundedRectangleShape(\n item_width=dk.DivFixedSize(value=32),\n item_height=dk.DivFixedSize(value=32),\n corner_radius=dk.DivFixedSize(value=100)\n ),\n ),\n track_active_style=dk.DivShapeDrawable(\n color=\"#00b300\",\n shape=dk.DivRoundedRectangleShape(\n item_height=dk.DivFixedSize(value=6)\n )\n ),\n track_inactive_style=dk.DivShapeDrawable(\n color=\"#20000000\",\n shape=dk.DivRoundedRectangleShape(\n item_height=dk.DivFixedSize(value=6)\n )\n )\n )\n )\n ]\n)\n\n```\n\nThis example might be serialised like this:\n\n```python\nimport json\n\nprint(json.dumps(slider.dict(), indent=1))\n# {\n# \"log_id\": \"sample_card\",\n# \"states\": [\n# {\n# \"div\": {\n# \"type\": \"slider\",\n# \"max_value\": 10,\n# \"min_value\": 1,\n# \"thumb_style\": {\n# \"type\": \"shape_drawable\",\n# \"color\": \"#00b300\",\n# \"shape\": {\n# \"type\": \"rounded_rectangle\",\n# \"corner_radius\": {\n# \"type\": \"fixed\",\n# \"value\": 100\n# },\n# \"item_height\": {\n# \"type\": \"fixed\",\n# \"value\": 32\n# },\n# \"item_width\": {\n# \"type\": \"fixed\",\n# \"value\": 32\n# }\n# },\n# \"stroke\": {\n# \"color\": \"#ffffff\",\n# \"width\": 3\n# }\n# },\n# \"track_active_style\": {\n# \"type\": \"shape_drawable\",\n# \"color\": \"#00b300\",\n# \"shape\": {\n# \"type\": \"rounded_rectangle\",\n# \"item_height\": {\n# \"type\": \"fixed\",\n# \"value\": 6\n# }\n# }\n# },\n# \"track_inactive_style\": {\n# \"type\": \"shape_drawable\",\n# \"color\": \"#20000000\",\n# \"shape\": {\n# \"type\": \"rounded_rectangle\",\n# \"item_height\": {\n# \"type\": \"fixed\",\n# \"value\": 6\n# }\n# }\n# },\n# \"width\": {\n# \"type\": \"match_parent\"\n# }\n# },\n# \"state_id\": 0\n# }\n# ]\n# }\n```\n\nTemplating and DRY\n------------------\n\nOf course, manually building blocks from your code every time is boring. \nSo, the first idea is to move the initialization of DivKit objects \ninto functions.\n\n```python\n# Naive DRY example which strictly non-recommended\nimport pydivkit as dk\n\n\ndef get_size(value: int = 32) -> dk.DivFixedSize:\n return dk.DivFixedSize(value=value)\n\n\ndef get_shape() -> dk.DivShape:\n return dk.DivShape(\n item_width=get_size(),\n item_height=get_size(),\n corner_radius=get_size(100)\n )\n\n \nslider_shape = get_shape()\n\nslider = dk.DivData(\n log_id=\"sample_card\",\n states=[\n dk.DivDataState(\n # other arguments\n div=dk.DivSlider(\n thumb_style=dk.DivShapeDrawable(\n shape=slider_shape,\n # other arguments\n ),\n # other arguments\n )\n )\n ]\n)\n```\n\nLooks a little better, but this approach doesn't scale well. To simplify layout \nand save traffic, DivKit has templates. This is a way to layout similar elements\nwithout having to declare the complete json, but just declare a template and use\nthis many times in similar items.\n\n**PyDivKit supports defining templates through the inheritance.**\n\nLet's define an example card:\n\n```python\nimport json\n\nimport pydivkit as dk\n\n\nclass CategoriesItem(dk.DivContainer):\n \"\"\"\n Class inherited from dk.DivContainer will have a template\n \"\"\"\n\n # Special object for mark this fields a DivKit field in template\n icon_url: str = dk.Field()\n text: str = dk.Field()\n\n # Set defaults layout for in the template\n width = dk.DivWrapContentSize()\n background = [dk.DivSolidBackground(color=\"#f0f0f0\")]\n content_alignment_vertical = dk.DivAlignmentVertical.CENTER\n orientation = dk.DivContainerOrientation.HORIZONTAL\n paddings = dk.DivEdgeInsets(left=12, right=12, top=10, bottom=10)\n border = dk.DivBorder(corner_radius=12)\n items = [\n dk.DivImage(\n width=dk.DivFixedSize(value=20),\n height=dk.DivFixedSize(value=20),\n margins=dk.DivEdgeInsets(right=6),\n\n # Special object Ref it's a reference for Field property\n image_url=dk.Ref(icon_url),\n ),\n dk.DivText(\n width=dk.DivWrapContentSize(),\n max_lines=1,\n\n # Special object Ref it's a reference for Field property\n text=dk.Ref(text),\n ),\n ]\n\n\nBASE_URL = \"https://leonardo.edadeal.io/dyn/re/segments/level1/96\"\n\n\n# So after class definition you might use all the `Field` marked property\n# names as an argument.\n\ngallery = dk.DivGallery(\n items=[\n CategoriesItem(\n text=\"Food\", icon_url=f\"{BASE_URL}/food.png\",\n ),\n CategoriesItem(\n text=\"Alcohol\", icon_url=f\"{BASE_URL}/alcohol.png\",\n ),\n CategoriesItem(\n text=\"Household\", icon_url=f\"{BASE_URL}/household.png\",\n ),\n ]\n)\n\nprint(json.dumps(dk.make_div(gallery), indent=1, ensure_ascii=False))\n# {\n# \"templates\": {\n# \"__main__.CategoriesItem\": {\n# \"type\": \"container\",\n# \"background\": [\n# {\n# \"type\": \"solid\",\n# \"color\": \"#f0f0f0\"\n# }\n# ],\n# \"border\": {\n# \"corner_radius\": 12\n# },\n# \"content_alignment_vertical\": \"center\",\n# \"items\": [\n# {\n# \"type\": \"image\",\n# \"height\": {\n# \"type\": \"fixed\",\n# \"value\": 20\n# },\n# \"$image_url\": \"icon_url\",\n# \"margins\": {\n# \"right\": 6\n# },\n# \"width\": {\n# \"type\": \"fixed\",\n# \"value\": 20\n# }\n# },\n# {\n# \"type\": \"text\",\n# \"max_lines\": 1,\n# \"$text\": \"text\",\n# \"width\": {\n# \"type\": \"wrap_content\"\n# }\n# }\n# ],\n# \"orientation\": \"horizontal\",\n# \"paddings\": {\n# \"bottom\": 10,\n# \"left\": 12,\n# \"right\": 12,\n# \"top\": 10\n# },\n# \"width\": {\n# \"type\": \"wrap_content\"\n# }\n# }\n# },\n# \"card\": {\n# \"log_id\": \"card\",\n# \"states\": [\n# {\n# \"div\": {\n# \"type\": \"gallery\",\n# \"items\": [\n# {\n# \"type\": \"__main__.CategoriesItem\",\n# \"icon_url\": \"https://leonardo.edadeal.io/dyn/re/segments/level1/96/food.png\",\n# \"text\": \"Food\"\n# },\n# {\n# \"type\": \"__main__.CategoriesItem\",\n# \"icon_url\": \"https://leonardo.edadeal.io/dyn/re/segments/level1/96/alcohol.png\",\n# \"text\": \"Alcohol\"\n# },\n# {\n# \"type\": \"__main__.CategoriesItem\",\n# \"icon_url\": \"https://leonardo.edadeal.io/dyn/re/segments/level1/96/household.png\",\n# \"text\": \"Household\"\n# }\n# ]\n# },\n# \"state_id\": 0\n# }\n# ]\n# }\n# }\n```\n\nTemplate names\n--------------\n\nBy default, templates are collecting by the metaclass into shared storage when \nthe class is declaring at import time, and have the \nformat `{module_name}.{class_name}`.\n\nThe following example, sure will not occur in the wild, shows a warning if \nsuddenly the names of the classes, and hence the templates, conflict.\n\n```python\nimport pydivkit as dk\n\n\nclass MyTemplate(dk.DivContainer):\n width = dk.DivWrapContentSize()\n\n\nclass MyTemplate(dk.DivContainer):\n pass\n\n# RuntimeWarning: Template 'test.MyTemplate' already defined in \n# <class 'test.MyTemplate'> and will be replaced to <class 'test.MyTemplate'>\n```\n\nAlso, if you do not want to show the structure of your project to the outside, \nor for some reason you need to make the example above clean, you can rename the\ntemplate by declaring a special attribute `__template_name__`\n\n```python\nimport pydivkit as dk\n\n\nclass MyTemplate(dk.DivContainer):\n width = dk.DivWrapContentSize()\n\nprint(MyTemplate.template_name)\n# >>> test.MyTemplate\n\nclass MyTemplate(dk.DivContainer):\n __template_name__ = \"MyTemplate2\"\n\nprint(MyTemplate.template_name)\n# >>> MyTemplate2\n```\n",
"bugtrack_url": null,
"license": null,
"summary": "DivKit python library",
"version": "32.7.1",
"project_urls": {
"Homepage": "https://github.com/divkit/divkit/tree/main/json-builder/python",
"Repository": "https://github.com/divkit/divkit/tree/main/json-builder/python"
},
"split_keywords": [
"divkit",
" sdk"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "e38ebca02604e65c7b262a9ef62783e7b399788789774dff93f1aaf0a78d23ba",
"md5": "1518499dcccb92f47551945a55700f73",
"sha256": "0e4368bc711bc4e38f49f4d8ea33f2dec6e5807c35ed37c8892ba413cf2efbc3"
},
"downloads": -1,
"filename": "pydivkit-32.7.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "1518499dcccb92f47551945a55700f73",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.8",
"size": 196591,
"upload_time": "2025-07-08T16:31:42",
"upload_time_iso_8601": "2025-07-08T16:31:42.620340Z",
"url": "https://files.pythonhosted.org/packages/e3/8e/bca02604e65c7b262a9ef62783e7b399788789774dff93f1aaf0a78d23ba/pydivkit-32.7.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "fe18847bb425f707e7a360f6f1cc14428baed391824158e6a8d38614a8d30d56",
"md5": "6705e98696a16b0a08cc1c954bc4524c",
"sha256": "07705b3786ef52956d5829cc793ea969e6e948f3400c51556f6e775ce0bc9ba8"
},
"downloads": -1,
"filename": "pydivkit-32.7.1.tar.gz",
"has_sig": false,
"md5_digest": "6705e98696a16b0a08cc1c954bc4524c",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.8",
"size": 92110,
"upload_time": "2025-07-08T16:31:44",
"upload_time_iso_8601": "2025-07-08T16:31:44.311260Z",
"url": "https://files.pythonhosted.org/packages/fe/18/847bb425f707e7a360f6f1cc14428baed391824158e6a8d38614a8d30d56/pydivkit-32.7.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-08 16:31:44",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "divkit",
"github_project": "divkit",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "pydivkit"
}
JSON
