Skip to content

README-en_US.md

Latest commit

 

History

History
465 lines (358 loc) · 12.1 KB

README-en_US.md

File metadata and controls

465 lines (358 loc) · 12.1 KB

feffery-dash-utils

简体中文 | English

Contains a series of tool functions/classes designed to enhance the development efficiency of Dash applications.

Pyhton GitHub PyPI Ruff

Table of Contents

Install
Use with vscode plugin
Utils List
Contribute
Roadmap

Install

pip install feffery-dash-utils -U

Use with vscode plugin

In vscode, with the plugin feffery-dash-snippets, you can quickly import various utility functions and classes. In a Python file, typing utils: will trigger the relevant quick commands.

Utils List

style()

Used for quickly generating the style parameter dictionary of Dash components, it includes most of the commonly used css properties in camelCase naming format. Hovering the mouse over the parameter name in common IDEs will display the corresponding Chinese and English property introductions, which are automatically generated based on w3cschool.

Usage Example

from feffery_dash_utils.style_utils import style

# Method one: Directly write key-value pair styles
fac.AntdText(
    'Test',
    style=style(
        fontSize=16,
        color='red'
    )
)

# Method two: Parse CSS code snippets
fac.AntdText(
    'Test',
    style=style(
        """
.IvkwhTOsc9wu6RdvHESR .yK52Sq0w7wspWaS28YNl {
    width: 91.46%;
    margin-left: 4.27%;
    margin-bottom: 5%;
    position: relative;
}"""
    )
)

# Method three: Mixed use
fac.AntdText(
    'Test',
    style=style(
        """
.IvkwhTOsc9wu6RdvHESR .yK52Sq0w7wspWaS28YNl {
    width: 91.46%;
    margin-left: 4.27%;
    margin-bottom: 5%;
    position: relative;
}""",
        fontSize=16,
        color='red'
    )
)

TreeManager

Used for quick management operations on tree structure data that components like AntdTree and AntdTreeSelect depend on. The specific methods included are:

update_tree_node()

Used to perform overall or incremental updates on a specified key corresponding node in the tree structure data.

Usage Example

from feffery_dash_utils.tree_utils import TreeManager

# Example tree data
demo_tree = [
    {
        'title': 'Node 1',
        'key': 'Node 1',
        'children': [
            {
                'title': 'Node 1-1',
                'key': 'Node 1-1',
                'children': [
                    {
                        'title': 'Node 1-1-1',
                        'key': 'Node 1-1-1',
                    },
                    {
                        'title': 'Node 1-1-2',
                        'key': 'Node 1-1-2',
                    },
                ],
            }
        ],
    },
    {'title': 'Node 2', 'key': 'Node 2'},
]

# Replace a specified node in the example tree data as a whole
TreeManager.update_tree_node(
    demo_tree,
    'Node 1-1',
    {'title': 'Node 1-1', 'key': 'Node 1-1'},
)

# Incrementally update a specified node in the example tree data
TreeManager.update_tree_node(
    demo_tree,
    'Node 1-1',
    {'title': 'Node 1-1new'},
    'overlay',
)

add_node_before()

Insert a new sibling node before the specified key corresponding node in the tree structure data.

Usage Example

from feffery_dash_utils.tree_utils import TreeManager

# Example tree data
demo_tree = [
    {
        'title': 'Node 1',
        'key': 'Node 1',
        'children': [
            {
                'title': 'Node 1-1',
                'key': 'Node 1-1',
                'children': [
                    {
                        'title': 'Node 1-1-1',
                        'key': 'Node 1-1-1',
                    },
                    {
                        'title': 'Node 1-1-2',
                        'key': 'Node 1-1-2',
                    },
                ],
            }
        ],
    },
    {'title': 'Node 2', 'key': 'Node 2'},
]

# Insert a new sibling node before the specified node in the example tree data
TreeManager.add_node_before(
    demo_tree,
    'Node 1-1',
    {'title': 'Node 1-0', 'key': 'Node 1-0'},
)

add_node_after()

Insert a new sibling node after the specified key corresponding node in the tree structure data.

Usage Example

from feffery_dash_utils.tree_utils import TreeManager

# Example tree data
demo_tree = [
    {
        'title': 'Node 1',
        'key': 'Node 1',
        'children': [
            {
                'title': 'Node 1-1',
                'key': 'Node 1-1',
                'children': [
                    {
                        'title': 'Node 1-1-1',
                        'key': 'Node 1-1-1',
                    },
                    {
                        'title': 'Node 1-1-2',
                        'key': 'Node 1-1-2',
                    },
                ],
            }
        ],
    },
    {'title': 'Node 2', 'key': 'Node 2'},
]

# Insert a new sibling node after the specified node in the example tree data
TreeManager.add_node_after(
    demo_tree,
    'Node 1-1',
    {'title': 'Node 1-2', 'key': 'Node 1-2'},
)

delete_node()

Delete the node corresponding to the specified key in the tree structure data.

Usage Example

from feffery_dash_utils.tree_utils import TreeManager

# Example tree data
demo_tree = [
    {
        'title': 'Node 1',
        'key': 'Node 1',
        'children': [
            {
                'title': 'Node 1-1',
                'key': 'Node 1-1',
                'children': [
                    {
                        'title': 'Node 1-1-1',
                        'key': 'Node 1-1-1',
                    },
                    {
                        'title': 'Node 1-1-2',
                        'key': 'Node 1-1-2',
                    },
                ],
            }
        ],
    },
    {'title': 'Node 2', 'key': 'Node 2'},
]

# Delete the specified node in the example tree data
TreeManager.delete_node(demo_tree, 'Node 2')

get_node()

Query the node corresponding to the specified key in the tree structure data.

Usage Example

from feffery_dash_utils.tree_utils import TreeManager

# Example tree data
demo_tree = [
    {
        'title': 'Node 1',
        'key': 'Node 1',
        'children': [
            {
                'title': 'Node 1-1',
                'key': 'Node 1-1',
                'children': [
                    {
                        'title': 'Node 1-1-1',
                        'key': 'Node 1-1-1',
                    },
                    {
                        'title': 'Node 1-1-2',
                        'key': 'Node 1-1-2',
                    },
                ],
            }
        ],
    },
    {'title': 'Node 2', 'key': 'Node 2'},
]

# Query the specified node in the example tree data
TreeManager.get_node(demo_tree, 'Node 1-1')

# Query a specified node that does not exist in the example tree data (will return None)
TreeManager.get_node(demo_tree, 'Node 1-666')

Translator

Used for quickly building an internationalization and multi-language solution in Dash applications, driven by front-end cookies and local internationalization configuration files.

Usage Example

Example applications can be found in i18n_test_app.py and i18n_multi_test_app.py, and reference configuration files can be found in locales.json, locales1.json, and locales2.json.

dashboard_components

Built-in data dashboard page building common custom components, including:

welcome_card()

Welcome card.

blank_card()

Blank card.

simple_chart_card()

Simple chart card.

index_card()

Index card.

version_utils

Provides a series of utility functions related to project dependency versions, including Python version checking and dependency library version checking.

check_python_version()

Used to check if the current Python version meets the project requirements.

Usage Example

from feffery_dash_utils.version_utils import check_python_version

check_python_version(
    min_version='3.8',
    max_version='3.12'
)

check_dependencies_version()

Used to check if the current project dependency library versions meet the project requirements.

Usage Example

from feffery_dash_utils.version_utils import check_dependencies_version

check_dependencies_version(
    rules=[
        {
            'name': 'dash',
            'specifier': '<=2.18.2'
        }
    ]
)

Contribute

git clone https://github.com/CNFeffery/feffery-dash-utils.git
cd feffery-dash-utils
# Install dependencies required for the development environment
pip install -r requirements/dev.txt

Roadmap

  • Style-related utility function submodule style_utils
    • style parameter writing assistant function style()
  • Template-related utility function submodule template_utils
    • Dashboard common custom component submodule dashboard_components
      • Welcome card welcome_card()
      • Blank card blank_card()
      • Simple chart card simple_chart_card()
      • Index card index_card()
  • Tree processing-related utility function submodule tree_utils
    • Tree data structure management class TreeManager
      • Tree node update function update_tree_node()
      • Tree node front insertion function add_node_before()
      • Tree node rear insertion function add_node_after()
      • Tree node deletion function delete_node()
      • Tree node query function get_node()
  • Internationalization-related utility function submodule i18n_utils
    • Text content quick internationalization operation class Translator
  • Version control-related utility function submodule version_utils
    • Python version check function check_python_version()
    • Dependencies version check function check_dependencies_version()
  • Component parameter auxiliary generation utility function submodule component_prop_utils
  • Auxiliary generation utility function to_box_data() for the data parameter of the fact.AntdBox box plot component