pyfcstm 0.0.1__py3-none-any.whl → 0.1.0__py3-none-any.whl

pyfcstm/config/meta.py

@@ -7,7 +7,7 @@ Overview:
 __TITLE__ = 'pyfcstm'
 
 #: Version of this project.
-__VERSION__ = '0.0.1'
+__VERSION__ = '0.1.0'
 
 #: Short description of the project, will be included in ``setup.py``.
 __DESCRIPTION__ = ('A Python framework for parsing finite state machine DSL and '

pyfcstm/entry/generate.py

@@ -14,6 +14,7 @@ from .base import CONTEXT_SETTINGS
 from ..dsl import parse_with_grammar_entry
 from ..model import parse_dsl_node_to_state_machine
 from ..render import StateMachineCodeRenderer
+from ..utils import auto_decode
 
 
 def _add_generate_subcommand(cli: click.Group) -> click.Group:
@@ -67,7 +68,7 @@ def _add_generate_subcommand(cli: click.Group) -> click.Group:
 
         :return: None
         """
-        code = pathlib.Path(input_code_file).read_text()
+        code = auto_decode(pathlib.Path(input_code_file).read_bytes())
         ast_node = parse_with_grammar_entry(code, entry_name='state_machine_dsl')
         model = parse_dsl_node_to_state_machine(ast_node)
 

pyfcstm/entry/plantuml.py

@@ -13,6 +13,7 @@ import click
 from .base import CONTEXT_SETTINGS
 from ..dsl import parse_with_grammar_entry
 from ..model import parse_dsl_node_to_state_machine
+from ..utils import auto_decode
 
 
 def _add_plantuml_subcommand(cli: click.Group) -> click.Group:
@@ -55,7 +56,7 @@ def _add_plantuml_subcommand(cli: click.Group) -> click.Group:
         :param output_file: Path to the output file for PlantUML code (stdout if None)
         :type output_file: str or None
         """
-        code = pathlib.Path(input_code_file).read_text()
+        code = auto_decode(pathlib.Path(input_code_file).read_bytes())
         ast_node = parse_with_grammar_entry(code, entry_name='state_machine_dsl')
         model = parse_dsl_node_to_state_machine(ast_node)
         if output_file is not None:

pyfcstm/render/render.py

@@ -65,6 +65,7 @@ from .expr import create_expr_render_template, fn_expr_render, _KNOWN_STYLES
 from .func import process_item_to_object
 from ..dsl import node as dsl_nodes
 from ..model import StateMachine
+from ..utils import auto_decode
 
 
 class StateMachineCodeRenderer:
@@ -209,7 +210,7 @@ class StateMachineCodeRenderer:
         :raises jinja2.exceptions.TemplateError: If there's an error in the template
         :raises IOError: If there's an error reading or writing files
         """
-        tp = self.env.from_string(pathlib.Path(template_file).read_text())
+        tp = self.env.from_string(auto_decode(pathlib.Path(template_file).read_bytes()))
         if os.path.dirname(output_file):
             os.makedirs(os.path.dirname(self.config_file), exist_ok=True)
         os.makedirs(os.path.dirname(output_file), exist_ok=True)

pyfcstm/utils/__init__.py

@@ -1,4 +1,5 @@
 from .binary import is_binary_file
+from .decode import auto_decode
 from .doc import format_multiline_comment
 from .jinja2 import add_builtins_to_env, add_settings_for_env
 from .json import IJsonOp

pyfcstm/utils/decode.py

@@ -0,0 +1,103 @@
+"""
+Utilities for automatic text decoding with a focus on Chinese encodings.
+
+This module provides functionality to automatically detect and decode text data
+from various encodings, with special emphasis on Chinese character encodings.
+It includes a comprehensive list of Chinese encodings commonly used on Windows
+systems and a robust auto-detection mechanism that tries multiple encodings
+until successful decoding is achieved.
+"""
+
+import sys
+from typing import Union
+
+import chardet
+from hbutils.collection import unique
+
+windows_chinese_encodings = [
+    'utf-8',  # UTF-8 encoding, Unicode standard
+    'gbk',  # Most common default encoding for Chinese Windows
+    'gb2312',  # Common encoding for Simplified Chinese, subset of GBK
+    'gb18030',  # Chinese national standard encoding, includes all Chinese characters
+    'big5',  # Common encoding for Traditional Chinese (Taiwan, Hong Kong)
+    'cp936',  # Windows code page for Simplified Chinese, essentially an alias for GBK
+    'cp950',  # Windows code page for Traditional Chinese, approximately equivalent to Big5
+    'hz',  # Early Chinese character encoding
+    # 'iso-2022-cn',  # ISO standard encoding for Chinese
+    'euc-cn',  # Extended Unix Code for Chinese
+    'utf-16',  # Default Unicode encoding used by Windows Notepad
+    'utf-16-le',  # Little-endian UTF-16 encoding, commonly used in Windows
+    'utf-16-be',  # Big-endian UTF-16 encoding
+    'utf-32',  # 32-bit Unicode encoding
+    'utf-32-le',  # Little-endian UTF-32 encoding
+    'utf-32-be'  # Big-endian UTF-32 encoding
+]
+
+
+def _decode(data: bytes, encoding: str) -> str:
+    """
+    Decode bytes data using the specified encoding.
+
+    :param data: The bytes data to decode
+    :type data: bytes
+    :param encoding: The encoding to use for decoding
+    :type encoding: str
+
+    :return: The decoded string
+    :rtype: str
+    :raises UnicodeDecodeError: If the data cannot be decoded with the specified encoding
+    """
+    return data.decode(encoding)
+
+
+def auto_decode(data: Union[bytes, bytearray]) -> str:
+    """
+    Automatically decode bytes data by trying multiple encodings.
+
+    This function attempts to decode the input data using multiple encodings in the following order:
+
+    1. The encoding detected by chardet
+    2. Common Chinese encodings used in Windows
+    3. The default system encoding
+
+    The function tries each encoding until successful decoding is achieved. If all
+    encodings fail, it raises the UnicodeDecodeError from the encoding that managed
+    to decode the most characters before failing.
+
+    :param data: The bytes data to decode
+    :type data: Union[bytes, bytearray]
+
+    :return: The decoded string
+    :rtype: str
+    :raises UnicodeDecodeError: If the data cannot be decoded with any of the attempted encodings
+
+    Example::
+
+        >>> text_bytes = b'\\xc4\\xe3\\xba\\xc3'  # "你好" in GBK encoding
+        >>> auto_decode(text_bytes)
+        '你好'
+    """
+    if len(data) >= 30:
+        _elist = list(filter(bool, unique([
+            chardet.detect(data)['encoding'],
+            *windows_chinese_encodings,
+            sys.getdefaultencoding(),
+        ])))
+    else:
+        _elist = list(filter(bool, unique([
+            *windows_chinese_encodings,
+            sys.getdefaultencoding(),
+            chardet.detect(data)['encoding'],
+        ])))
+
+    last_err = None
+    for enc in _elist:
+        try:
+            text = _decode(data, enc)
+        except UnicodeDecodeError as err:
+            if last_err is None or err.start > last_err.start:
+                last_err = err
+        else:
+            return text
+
+    raise last_err

{pyfcstm-0.0.1.dist-info → pyfcstm-0.1.0.dist-info}/METADATA

@@ -1,11 +1,11 @@
 Metadata-Version: 2.1
 Name: pyfcstm
-Version: 0.0.1
+Version: 0.1.0
 Summary: A Python framework for parsing finite state machine DSL and generating executable code in multiple target languages.
 Home-page: https://github.com/hansbug/pyfcstm
 Author: HansBug
 Author-email: hansbug@buaa.edu.cn
-License: Apache License, Version 2.0
+License: GNU Lesser General Public License v3 (LGPLv3)
 Project-URL: Homepage, https://github.com/hansbug/pyfcstm
 Project-URL: Documentation, https://hansbug.github.io/pyfcstm/
 Project-URL: Source, https://github.com/hansbug/pyfcstm
@@ -17,12 +17,14 @@ Project-URL: CI, https://github.com/hansbug/pyfcstm/actions
 Project-URL: Coverage, https://codecov.io/gh/hansbug/pyfcstm
 Project-URL: Wiki, https://github.com/hansbug/pyfcstm/wiki
 Project-URL: License, https://github.com/hansbug/pyfcstm/blob/main/LICENSE
-Keywords: huggingface,download,upload,batch processing,data processing,machine learning,ai
+Keywords: state-machine,code-generation,compiler,template-engine,modelling
 Classifier: Development Status :: 5 - Production/Stable
 Classifier: Intended Audience :: Developers
 Classifier: Intended Audience :: Science/Research
 Classifier: Intended Audience :: Information Technology
-Classifier: License :: OSI Approved :: MIT License
+Classifier: Intended Audience :: Manufacturing
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: GNU Lesser General Public License v3 (LGPLv3)
 Classifier: Programming Language :: Python
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3 :: Only
@@ -37,11 +39,23 @@ Classifier: Operating System :: POSIX
 Classifier: Operating System :: Microsoft :: Windows
 Classifier: Operating System :: MacOS
 Classifier: Topic :: Scientific/Engineering
-Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Classifier: Topic :: Scientific/Engineering :: Visualization
+Classifier: Topic :: Software Development
 Classifier: Topic :: Software Development :: Libraries
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
-Classifier: Topic :: Internet :: File Transfer Protocol (FTP)
+Classifier: Topic :: Software Development :: Code Generators
+Classifier: Topic :: Software Development :: Compilers
+Classifier: Topic :: Software Development :: Interpreters
+Classifier: Topic :: Software Development :: Pre-processors
+Classifier: Topic :: Software Development :: Build Tools
+Classifier: Topic :: Text Processing
+Classifier: Topic :: Text Processing :: Linguistic
+Classifier: Topic :: Text Processing :: Markup
+Classifier: Topic :: System :: Systems Administration
+Classifier: Topic :: System :: Monitoring
 Classifier: Topic :: Utilities
+Classifier: Topic :: Documentation
 Classifier: Typing :: Typed
 Classifier: Natural Language :: English
 Requires-Python: >=3.7
@@ -56,6 +70,7 @@ Requires-Dist: jinja2 >=3
 Requires-Dist: unidecode
 Requires-Dist: pathspec
 Requires-Dist: click >=8
+Requires-Dist: chardet
 Provides-Extra: build
 Requires-Dist: pyinstaller >=4.7 ; extra == 'build'
 Requires-Dist: setuptools ; extra == 'build'
@@ -111,6 +126,7 @@ Requires-Dist: natsort ; extra == 'test'
 ![Comments](https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/HansBug/7eb8c32d6549edaa09592ca2a5a47187/raw/comments.json)
 [![Maintainability](https://api.codeclimate.com/v1/badges/5b6e14a915b63faeae90/maintainability)](https://codeclimate.com/github/HansBug/pyfcstm/maintainability)
 [![codecov](https://codecov.io/gh/hansbug/pyfcstm/graph/badge.svg?token=NYSTMMTC2F)](https://codecov.io/gh/hansbug/pyfcstm)
+[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/HansBug/pyfcstm)
 
 [![Docs Deploy](https://github.com/hansbug/pyfcstm/workflows/Docs%20Deploy/badge.svg)](https://github.com/hansbug/pyfcstm/actions?query=workflow%3A%22Docs+Deploy%22)
 [![Code Test](https://github.com/hansbug/pyfcstm/workflows/Code%20Test/badge.svg)](https://github.com/hansbug/pyfcstm/actions?query=workflow%3A%22Code+Test%22)
@@ -127,12 +143,129 @@ Requires-Dist: natsort ; extra == 'test'
 
 A Python framework for parsing finite state machine DSL and generating executable code in multiple target languages.
 
+## Installation
+
+You can simply install it with `pip` command line from the official PyPI site.
+
+```shell
+pip install pyfcstm
+```
+
+For more information about installation, you can refer
+to [Installation Documentation](https://hansbug.github.io/pyfcstm/main/tutorials/installation/index.html).
+
+## How To Use It
+
+### Use With CLI
+
+You can use this with CLI command
+
+```shell
+pyfcstm --help
+```
+
+* Generate Plantuml Code For Visualization
+
+```shell
+pyfcstm plantuml -i test_dsl_code.fcstm
+```
+
+Here is a simple code example, you can try this out
+
+```
+def int a = 0;
+def int b = 0x0;
+def int round_count = 0;  // define variables
+state TrafficLight {
+    >> during before {
+        a = 0;
+    }
+    >> during before abstract FFT;
+    >> during before abstract TTT;
+    >> during after {
+        a = 0xff;
+        b = 0x1;
+    }
+
+    !InService -> [*] :: Error;
+
+    state InService {
+        enter {
+            a = 0;
+            b = 0;
+            round_count = 0;
+        }
+
+        enter abstract InServiceAbstractEnter /*
+            Abstract Operation When Entering State 'InService'
+            TODO: Should be Implemented In Generated Code Framework
+        */
+
+        // for non-leaf state, either 'before' or 'after' aspect keyword should be used for during block
+        during before abstract InServiceBeforeEnterChild /*
+            Abstract Operation Before Entering Child States of State 'InService'
+            TODO: Should be Implemented In Generated Code Framework
+        */
+
+        during after abstract InServiceAfterEnterChild /*
+            Abstract Operation After Entering Child States of State 'InService'
+            TODO: Should be Implemented In Generated Code Framework
+        */
+
+        exit abstract InServiceAbstractExit /*
+            Abstract Operation When Leaving State 'InService'
+            TODO: Should be Implemented In Generated Code Framework
+        */
+
+        state Red {
+            during {  // no aspect keywords ('before', 'after') should be used for during block of leaf state
+                a = 0x1 << 2;
+            }
+        }
+        state Yellow;
+        state Green;
+        [*] -> Red :: Start effect {
+            b = 0x1;
+        };
+        Red -> Green effect {
+            b = 0x3;
+        };
+        Green -> Yellow effect {
+            b = 0x2;
+        };
+        Yellow -> Red : if [a >= 10] effect {
+            b = 0x1;
+            round_count = round_count + 1;
+        };
+        Green -> Yellow : /Idle.E2;
+        Yellow -> Yellow : /E2;
+    }
+    state Idle;
+
+    [*] -> InService;
+    InService -> Idle :: Maintain;
+    Idle -> Idle :: E2;
+    Idle -> [*];
+}
+```
+
+* Generate Code With Given Template
+
+```shell
+pyfcstm generate -i test_dsl_code.fcstm -t template_dir/ -o generated_code_dir/
+```
+
+### Use With Pythonic API
+
+You can use this with pythonic API.
+
 ```python
 from pyfcstm.dsl import parse_with_grammar_entry
 from pyfcstm.model.model import parse_dsl_node_to_state_machine
 from pyfcstm.render import StateMachineCodeRenderer
 
 if __name__ == '__main__':
+    # Load AST Node From DSL Code
     ast_node = parse_with_grammar_entry("""
     def int a = 0;
     def int b = 0x0;
@@ -194,12 +327,16 @@ if __name__ == '__main__':
         Idle -> [*];
     }
     """, entry_name='state_machine_dsl')
+    # Load DSL Model From DSL AST Node
     model = parse_dsl_node_to_state_machine(ast_node)
 
+    # Load Template Directory
     renderer = StateMachineCodeRenderer(
-        # template_dir='test_template',
         template_dir='../fsm_generation_template'
     )
+    # Render to Given Directory Via Template Directory
     renderer.render(model, 'test_output_x')
-
 ```
+
+For more information about this DSL,
+see: [PyFCSTM DSL Syntax Tutorial](https://hansbug.github.io/pyfcstm/main/tutorials/dsl/index.html).

{pyfcstm-0.0.1.dist-info → pyfcstm-0.1.0.dist-info}/RECORD

@@ -1,7 +1,7 @@
 pyfcstm/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 pyfcstm/__main__.py,sha256=rqAJpNJgf8R-OZnKecjYyCrK_hJcQhHaO0UL6Vb92-8,75
 pyfcstm/config/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-pyfcstm/config/meta.py,sha256=EoP3nTEy-YXDjAFCroCE3FPRygrCLbja0bwPliRa_cQ,534
+pyfcstm/config/meta.py,sha256=z4hf_T3kF1MS6kkQlF4QsxASIvNRh93TTGLkjUQZnNQ,534
 pyfcstm/dsl/__init__.py,sha256=3GMEILDRArhkjz0vQPHOk_eiby74H94TOa3o-Tpo4x0,349
 pyfcstm/dsl/error.py,sha256=BEaroPj98Q8J12IT73rfPeb9y0TXjPG6llDo5GiqRIU,8878
 pyfcstm/dsl/listener.py,sha256=9J8QETMu40HxT20ZOJ4c9QWY7X_Y6AbEgkzoD-xTAg4,19633
@@ -20,8 +20,8 @@ pyfcstm/entry/__init__.py,sha256=3dO1hloAnUm_Sctxk_ERdaiqCF-ie8lijVjtXb-YE8g,35
 pyfcstm/entry/base.py,sha256=SC1UthaKaoXIWilU-pNLjpQZ9PWm8I1UYDBg2VSU8cM,3334
 pyfcstm/entry/cli.py,sha256=crBHD8yK16vkiyVDTG1zM6TCIfCs_Bu_nVoeGpQWpA0,269
 pyfcstm/entry/dispatch.py,sha256=LMXy8aNyvrY_ianK2FgKbRiZ7GjO3I9me2_c5gtX0qI,1868
-pyfcstm/entry/generate.py,sha256=gK8pB7okwRjTWquVm1HqMYXVJY_DkDEHxv6f6Kh7u3Y,3185
-pyfcstm/entry/plantuml.py,sha256=i07Fc-jxyVGA3_kOjhBllEbsQ652OWVvoK9WUGKzwns,2620
+pyfcstm/entry/generate.py,sha256=3u2xxCY49aMQ_24RPkx2P9THyJGDMuVoZINHxLk0eEE,3231
+pyfcstm/entry/plantuml.py,sha256=uZUZ_kxhxinh8Jw6nf0e4c2C14kfqH5eeRS3bbCDRbc,2666
 pyfcstm/model/__init__.py,sha256=aJ76DOX21iXRJN2xwsH7CiEG7iPkpDJMXKvEh9Xb9Q4,93
 pyfcstm/model/base.py,sha256=3H6Sf9uTfAZUNemSmR4L1aoSICG42EcrVncgQDZNAXY,1761
 pyfcstm/model/expr.py,sha256=X3eyOYMeZ66LdD0ZpwDjDRQUQrkpXtpSWLY9TILFzSI,18908
@@ -30,17 +30,18 @@ pyfcstm/render/__init__.py,sha256=Bettq3kIoswqSZQSxjQciMrmRZqkn5noaKoQO9d8Jlw,15
 pyfcstm/render/env.py,sha256=pjZnlvYLL8sA9lZupKtIHijrHOiAWBeBU_ytNYLxz1w,1106
 pyfcstm/render/expr.py,sha256=sT7uazQuEFrAFHBSTV0FviubNIYP-CTjhNhd4dO96Fo,7551
 pyfcstm/render/func.py,sha256=FZlQiKxKpOomH83FDqYYoeeclXlmm07zHYJk8MN5Cws,2663
-pyfcstm/render/render.py,sha256=QhVcwcNfeAH9Ioh59sW3JyoDt4cWG2SndMeW9PMoNbc,11531
-pyfcstm/utils/__init__.py,sha256=1gp84WrUSTmiAEzxpcek0RvlWyDLJVee9wcq4PcdxxA,282
+pyfcstm/render/render.py,sha256=FmhHJvoIwWFGpm-KqDqybadj9pZbo7-bIiNxnyBF2Fc,11577
+pyfcstm/utils/__init__.py,sha256=9Bhh0epIZ_zL3ynzN7LUG9ts3aBcSXMbxSr_fRCJIkg,314
 pyfcstm/utils/binary.py,sha256=6AnX6Hx4JFRHl0Y1A6OJ1b_1-QtzaajEywp0h-a4kbs,1196
+pyfcstm/utils/decode.py,sha256=V9WYt9_db_ddIB3PiSsGPPAO_aAeHinNRvA3W5jO6XM,3636
 pyfcstm/utils/doc.py,sha256=CNGQoxTl33KEAnEXl_sr4I97zNARaAa2IwKKt5IC1MA,1905
 pyfcstm/utils/jinja2.py,sha256=9lJFnsxfzTfc9Wj1twhk3e6aFgRzBW-mbhdOVudNcKw,4321
 pyfcstm/utils/json.py,sha256=WPubB5ObTNT8eEyGV3DcgFE8BuYxJUO8xYPx5_kvvCQ,3732
 pyfcstm/utils/text.py,sha256=wb4vIWB3mLne1R64x_MIS5qsIlGQ6cGCUVcbPlV21Hw,2895
 pyfcstm/utils/validate.py,sha256=87k1B-gzYd-mZP2N5-nsC8OeLZsfNTOCjp_5LUgsaxw,3129
-pyfcstm-0.0.1.dist-info/LICENSE,sha256=pWgb-bBdsU2Gd2kwAXxketnm5W_2u8_fIeWEgojfrxs,7651
-pyfcstm-0.0.1.dist-info/METADATA,sha256=qhTaf4e0f77jUkSZhaEkzLZP9FM55dPAlSzJAwc1hBc,9816
-pyfcstm-0.0.1.dist-info/WHEEL,sha256=iAkIy5fosb7FzIOwONchHf19Qu7_1wCWyFNR5gu9nU0,91
-pyfcstm-0.0.1.dist-info/entry_points.txt,sha256=Jh9a4hY-nMh5VTiuIBiZcM403biCHOwXk5hKNBr3Eok,53
-pyfcstm-0.0.1.dist-info/top_level.txt,sha256=0VZTj6MqIhOSyoQLYUk1inV0P34VgetNZIKrzj-HNqo,8
-pyfcstm-0.0.1.dist-info/RECORD,,
+pyfcstm-0.1.0.dist-info/LICENSE,sha256=pWgb-bBdsU2Gd2kwAXxketnm5W_2u8_fIeWEgojfrxs,7651
+pyfcstm-0.1.0.dist-info/METADATA,sha256=UD0bt8g15Yl44cOudHA7YEX6O6ghsCT6wGhHnY9U5J8,13742
+pyfcstm-0.1.0.dist-info/WHEEL,sha256=iAkIy5fosb7FzIOwONchHf19Qu7_1wCWyFNR5gu9nU0,91
+pyfcstm-0.1.0.dist-info/entry_points.txt,sha256=Jh9a4hY-nMh5VTiuIBiZcM403biCHOwXk5hKNBr3Eok,53
+pyfcstm-0.1.0.dist-info/top_level.txt,sha256=0VZTj6MqIhOSyoQLYUk1inV0P34VgetNZIKrzj-HNqo,8
+pyfcstm-0.1.0.dist-info/RECORD,,