MapleX 2.2.0.dev2__tar.gz → 3.0.0.dev2__tar.gz

{maplex-2.2.0.dev2 → maplex-3.0.0.dev2}/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 Ryuji Hazama
+Copyright (c) 2026 Ryuji Hazama
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

{maplex-2.2.0.dev2 → maplex-3.0.0.dev2}/MANIFEST.in

@@ -1,6 +1,9 @@
 include LICENSE
 include README.md
+include readmes/*.md
 include release/*
+include *.png
+recursive-include tests *.py
 
 exclude .gitignore
 exclude mapleOutputTest.py

maplex-3.0.0.dev2/PKG-INFO

@@ -0,0 +1,197 @@
+Metadata-Version: 2.4
+Name: MapleX
+Version: 3.0.0.dev2
+Summary: A Python library for simple logging, json file operations, Maple file format operations, and console color utilities.
+Author: RyujiHazama
+Project-URL: PyPI, https://pypi.org/project/MapleX/
+Project-URL: Homepage, https://github.com/Ryuji-Hazama
+Project-URL: Repository, https://github.com/Ryuji-Hazama/MapleTree
+Project-URL: Issues, https://github.com/Ryuji-Hazama/MapleTree/issues
+Project-URL: YouTube, https://www.youtube.com/@ryujihazama
+Project-URL: Instagram, https://www.instagram.com/ryujihazama/
+Keywords: logging,logger,json,file operations,maple file format,console colors
+Classifier: Programming Language :: Python :: 3.12
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: cryptography>=46.0.3
+Requires-Dist: pydantic>=2.12.5
+Dynamic: license-file
+
+# MapleX
+
+    MapleX is a Python library for simple logging, json file operations, Maple file format operations, and console color utilities.
+
+    ***You can install the package from pip with the following command.***
+
+```bash
+pip install MapleX
+```
+
+## Logger Class
+
+    Logger is a logging object for Python applications. It outputs application logs to log files and to console (standard output).
+
+    Easy and simple enough to use, yet highly practical. The best logging library for beginners and for personal projects.
+
+### Beginner Friendly
+
+#### Color Highlited Output
+
+    The output will be color-highlighted for better analysis based on the log level. (Not tested on macOS, and you need Windows Terminal for Windows OS)
+
+![Log output sample image](logOutputSample.png)
+
+#### Outputs Stack Trace
+
+    You can use a function to outputs error message and the stack trace at once.
+
+![Stack Trace output sample image](logErrorOutputSample.png)
+
+### Logger Sample
+
+```python
+import maplex
+
+logger = maplex.getLogger("FunctionName")
+logger.info("Hello there!")
+```
+
+This outputs to console:
+
+```console
+[INFO ][FunctionName] <module>(4) Hello there!
+```
+
+Also outputs to the log file:
+
+```log
+(PsNo) yyyy-MM-dd HH:mm:ss.fff [INFO ][FunctionName] <module>(4) Hello there!
+```
+
+[More details](https://github.com/Ryuji-Hazama/MapleTree/blob/main/readmes/README_Logger.md)
+
+[Logging Tips](https://github.com/Ryuji-Hazama/MapleTree/blob/main/readmes/LoggingTips.md)
+
+## MapleJson
+
+&nbsp;&nbsp;&nbsp;&nbsp;MapleJson class is a library class for convert data between `dict` data and JSON formatted file data.
+
+&nbsp;&nbsp;&nbsp;&nbsp;You can read, write and also encrypt a JSON file as a `dict` data.
+
+[More details](https://github.com/Ryuji-Hazama/MapleTree/blob/main/readmes/README_Json.md)
+
+## Maple File Format
+
+&nbsp;&nbsp;&nbsp;&nbsp;Maple is a file system that I created when I was a child. It's like a combination of the INI file and the Jason file. I made this format that is easy to read and write for both humans and machines.
+
+### Basic Format
+
+```text
+All data before MAPLE\n will be ignored
+
+MAPLE
+# Maple data must start with "MAPLE"
+
+*MAPLE_TIME
+yyyy/MM/dd HH:mm:ss.fffffff
+# Encoded time or optional time in the method parameter
+
+H *STATUS
+    # File status
+    ADT yyyy/MM/dd HH:mm:ss.fffffff
+    RDT yyyy/MM/dd HH:mm:ss.fffffff
+    CNT {int}
+    H #*
+        ADT is the most recent edited time
+        RDT is the second most recent edited time (before ADT)
+        CNT is the data count (Optional)
+    E *#
+E
+H *Header
+    # Headers include '*' are system headers
+E
+H Data Headers
+    H Sub Data Header
+        CMT Comments
+        # This is also a comment
+        Tags Properties
+        # Propaties cannot include 'CRLF.'
+        Tags2 Properties
+        # You cannot use the same tags in a Header except CMT and NTE in H NOTES
+        H Sub Data Header
+            Tags Propaties
+            # You can use the same tag in the child header,
+            # which is already used in the parents' header
+        E
+    E
+    H *NOTES NOTES_HEADER
+        # Note's header
+        NTE {strimg}
+        NTE ...
+        # Notes' main strings for the multi-line data
+        # COMMENTS IN THE "*NOTES" BLOCK WILL BE DELETED WHEN SAVING!
+    E
+    H #*
+        This is a comment block.
+        Starts with "H #*"
+        and ends with "E *#"
+    E *#
+E
+H Data Headers2
+E
+# "\nEOF\n" must be needed for all data
+EOF
+
+All datas after "\nEOF\n" will be ignored
+```
+
+[More details](https://github.com/Ryuji-Hazama/MapleTree/blob/main/readmes/README_MapleTree.md#maple-file)
+
+## MapleTree Class
+
+&nbsp;&nbsp;&nbsp;&nbsp;MapleTree class is a Python library for read, edit, and write the Maple formatted file from the Python code.  
+&nbsp;&nbsp;&nbsp;&nbsp;You can also automatically encrypt the file data using the library functions.
+
+[More details](https://github.com/Ryuji-Hazama/MapleTree/blob/main/readmes/README_MapleTree.md#mapletree-class)
+
+## Exceptions
+
+&nbsp;&nbsp;&nbsp;&nbsp;Excption classes are the specialized classes for MapleX to make your debug easier.
+
+[More details](https://github.com/Ryuji-Hazama/MapleTree/blob/main/readmes/README_Exceptions.md#exceptions)
+
+## Console Colors
+
+&nbsp;&nbsp;&nbsp;&nbsp;ConsoleColors class is a class library for color-highlight the standard output.
+
+[More details](https://github.com/Ryuji-Hazama/MapleTree/blob/main/readmes/README_ConsoleColors.md)
+
+## Install MapleX
+
+### From PyPI
+
+```bash
+[python[3] -m] pip install MapleX [--break-system-packages]
+```
+
+### Manual Installation
+
+1. Download `./dist/maplex-<version>-py3-none-any.whl`
+2. Run `[python[3] -m] pip install /path/to/downloaded/maplex-<version>-py3-none-any.whl [--break-system-packages]`
+
+### Build the Package by Yourself
+
+&nbsp;&nbsp;&nbsp;&nbsp;Run `python[3] -m build`  
+
+or
+
+&nbsp;&nbsp;&nbsp;&nbsp;Run `python[3] setup.py sdist bdist_wheel`
+
+### Unit test
+
+```bash
+python[3] -m unittest discover -s tests
+```

maplex-3.0.0.dev2/README.md

@@ -0,0 +1,175 @@
+# MapleX
+
+    MapleX is a Python library for simple logging, json file operations, Maple file format operations, and console color utilities.
+
+    ***You can install the package from pip with the following command.***
+
+```bash
+pip install MapleX
+```
+
+## Logger Class
+
+    Logger is a logging object for Python applications. It outputs application logs to log files and to console (standard output).
+
+    Easy and simple enough to use, yet highly practical. The best logging library for beginners and for personal projects.
+
+### Beginner Friendly
+
+#### Color Highlited Output
+
+    The output will be color-highlighted for better analysis based on the log level. (Not tested on macOS, and you need Windows Terminal for Windows OS)
+
+![Log output sample image](logOutputSample.png)
+
+#### Outputs Stack Trace
+
+    You can use a function to outputs error message and the stack trace at once.
+
+![Stack Trace output sample image](logErrorOutputSample.png)
+
+### Logger Sample
+
+```python
+import maplex
+
+logger = maplex.getLogger("FunctionName")
+logger.info("Hello there!")
+```
+
+This outputs to console:
+
+```console
+[INFO ][FunctionName] <module>(4) Hello there!
+```
+
+Also outputs to the log file:
+
+```log
+(PsNo) yyyy-MM-dd HH:mm:ss.fff [INFO ][FunctionName] <module>(4) Hello there!
+```
+
+[More details](https://github.com/Ryuji-Hazama/MapleTree/blob/main/readmes/README_Logger.md)
+
+[Logging Tips](https://github.com/Ryuji-Hazama/MapleTree/blob/main/readmes/LoggingTips.md)
+
+## MapleJson
+
+&nbsp;&nbsp;&nbsp;&nbsp;MapleJson class is a library class for convert data between `dict` data and JSON formatted file data.
+
+&nbsp;&nbsp;&nbsp;&nbsp;You can read, write and also encrypt a JSON file as a `dict` data.
+
+[More details](https://github.com/Ryuji-Hazama/MapleTree/blob/main/readmes/README_Json.md)
+
+## Maple File Format
+
+&nbsp;&nbsp;&nbsp;&nbsp;Maple is a file system that I created when I was a child. It's like a combination of the INI file and the Jason file. I made this format that is easy to read and write for both humans and machines.
+
+### Basic Format
+
+```text
+All data before MAPLE\n will be ignored
+
+MAPLE
+# Maple data must start with "MAPLE"
+
+*MAPLE_TIME
+yyyy/MM/dd HH:mm:ss.fffffff
+# Encoded time or optional time in the method parameter
+
+H *STATUS
+    # File status
+    ADT yyyy/MM/dd HH:mm:ss.fffffff
+    RDT yyyy/MM/dd HH:mm:ss.fffffff
+    CNT {int}
+    H #*
+        ADT is the most recent edited time
+        RDT is the second most recent edited time (before ADT)
+        CNT is the data count (Optional)
+    E *#
+E
+H *Header
+    # Headers include '*' are system headers
+E
+H Data Headers
+    H Sub Data Header
+        CMT Comments
+        # This is also a comment
+        Tags Properties
+        # Propaties cannot include 'CRLF.'
+        Tags2 Properties
+        # You cannot use the same tags in a Header except CMT and NTE in H NOTES
+        H Sub Data Header
+            Tags Propaties
+            # You can use the same tag in the child header,
+            # which is already used in the parents' header
+        E
+    E
+    H *NOTES NOTES_HEADER
+        # Note's header
+        NTE {strimg}
+        NTE ...
+        # Notes' main strings for the multi-line data
+        # COMMENTS IN THE "*NOTES" BLOCK WILL BE DELETED WHEN SAVING!
+    E
+    H #*
+        This is a comment block.
+        Starts with "H #*"
+        and ends with "E *#"
+    E *#
+E
+H Data Headers2
+E
+# "\nEOF\n" must be needed for all data
+EOF
+
+All datas after "\nEOF\n" will be ignored
+```
+
+[More details](https://github.com/Ryuji-Hazama/MapleTree/blob/main/readmes/README_MapleTree.md#maple-file)
+
+## MapleTree Class
+
+&nbsp;&nbsp;&nbsp;&nbsp;MapleTree class is a Python library for read, edit, and write the Maple formatted file from the Python code.  
+&nbsp;&nbsp;&nbsp;&nbsp;You can also automatically encrypt the file data using the library functions.
+
+[More details](https://github.com/Ryuji-Hazama/MapleTree/blob/main/readmes/README_MapleTree.md#mapletree-class)
+
+## Exceptions
+
+&nbsp;&nbsp;&nbsp;&nbsp;Excption classes are the specialized classes for MapleX to make your debug easier.
+
+[More details](https://github.com/Ryuji-Hazama/MapleTree/blob/main/readmes/README_Exceptions.md#exceptions)
+
+## Console Colors
+
+&nbsp;&nbsp;&nbsp;&nbsp;ConsoleColors class is a class library for color-highlight the standard output.
+
+[More details](https://github.com/Ryuji-Hazama/MapleTree/blob/main/readmes/README_ConsoleColors.md)
+
+## Install MapleX
+
+### From PyPI
+
+```bash
+[python[3] -m] pip install MapleX [--break-system-packages]
+```
+
+### Manual Installation
+
+1. Download `./dist/maplex-<version>-py3-none-any.whl`
+2. Run `[python[3] -m] pip install /path/to/downloaded/maplex-<version>-py3-none-any.whl [--break-system-packages]`
+
+### Build the Package by Yourself
+
+&nbsp;&nbsp;&nbsp;&nbsp;Run `python[3] -m build`  
+
+or
+
+&nbsp;&nbsp;&nbsp;&nbsp;Run `python[3] setup.py sdist bdist_wheel`
+
+### Unit test
+
+```bash
+python[3] -m unittest discover -s tests
+```

{maplex-2.2.0.dev2 → maplex-3.0.0.dev2}/pyproject.toml

@@ -4,14 +4,13 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "MapleX"
-version = "2.2.0.dev2"
-description = """
-MapleX: A Python library for Maple file format operations, with logging and console color utilities
-"""
+version = "3.0.0.dev2"
+description = """A Python library for simple logging, json file operations, Maple file format operations, and console color utilities."""
+keywords = ["logging", "logger", "json", "file operations", "maple file format", "console colors"]
 readme = "README.md"
 license-files = ["LICENSE"]
 authors = [
-    {name = "Ryuji Hazama"}
+    {name = "RyujiHazama"}
 ]
 dependencies = [
     "cryptography>=46.0.3",
@@ -26,6 +25,10 @@ requires-python = ">=3.12"
 
 [tool.setuptools.packages.find]
 where = ["src"]
+include = ["maplex*"]
+
+[tool.setuptools.package-data]
+"*" = ["tests/*.py"]
 
 [project.urls]
 PyPI = "https://pypi.org/project/MapleX/"

maplex-3.0.0.dev2/readmes/LoggingTips.md

@@ -0,0 +1 @@
+# Logging Tips

maplex-3.0.0.dev2/readmes/README_ConsoleColors.md

@@ -0,0 +1,50 @@
+# Console Colors
+
+## Standard colors
+
+|Key|Value|Color|
+|---|-----|-----|
+|`Black`|\\033\[30m|Black|
+|`Red`|\\033\[31m|Red|
+|`Green`|\\033\[32m|Green|
+|`Yellow`|\\033\[33m|Yellow|
+|`Blue`|\\033\[34m|Blue|
+|`Magenta`|\\033\[35m|Magenta|
+|`LightBlue`|\\033\[36m|LightBlue|
+|`White`|\\033\[37m|White|
+
+## Bright colors
+
+|Key|Value|Color|
+|---|-----|-----|
+|`bBlack`|\\033\[90m|Black|
+|`bRed`|\\033\[91m|Red|
+|`bGreen`|\\033\[92m|Green|
+|`bYellow`|\\033\[93m|Yellow|
+|`bBlue`|\\033\[94m|Blue|
+|`bMagenta`|\\033\[95m|Magenta|
+|`bLightBlue`|\\033\[96m|LightBlue|
+|`bWhite`|\\033\[97m|White|
+
+## Background colors
+
+|Key|Value|Color|
+|---|-----|-----|
+|`bgBlack`|\\033\[40m|Black|
+|`bgRed`|\\033\[41m|Red|
+|`bgGreen`|\\033\[42m|Green|
+|`bgYellow`|\\033\[43m|Yellow|
+|`bgBlue`|\\033\[44m|Blue|
+|`bgMagenta`|\\033\[45m|Magenta|
+|`bgLightBlue`|\\033\[46m|LightBlue|
+|`bgWhite`|\\033\[47m|White|
+
+## Other formats
+
+|Key|Value|Description|
+|---|-----|-----------|
+|`Bold`|\\033\[1m|Bold text|
+|`Italic`|\\033\[3m|Italic text|
+|`Underline`|\\033\[4m|Underlined text|
+|`Reversed`|\\033\[7m|Reversed colors|
+|`Reset`|\\033\[0m|Reset formatting|

maplex-3.0.0.dev2/readmes/README_Exceptions.md

@@ -0,0 +1,57 @@
+# Exceptions
+
+## `class MapleException(Exception)`
+
+    This is a basic exception class for MapleTree.
+
+## `class MapleFileNotFoundException(MapleException)`
+
+    This occurs when the file that was specified at the instance initialization was not found.
+
+## `class KeyEmptyException(MapleException)`
+
+    This occurs when `encrypt=True` is used at the instance initialization, but the key for encryption is missing (`None` or empty).
+
+## `class MapleFileLockedException(MapleException)`
+
+    This occurs when the instance tries to open the file, but the other instance has already locked the file.
+
+## `class MapleDataNotFoundException(MapleException)`
+
+    This occurs when the data is not found in the file.
+
+## `MapleEncryptionNotEnabledException(MapleException)`
+
+    This occurs when trying to encrypt Maple data, but the encryption flag is `False`.
+
+## `class MapleHeaderNotFoundException(MapleDataNotFoundException)`
+
+    This occurs when the header (specified by the user) is not found in the data.
+
+## `class MapleTagNotFoundException(MapleDataNotFoundException)`
+
+    This occurs when the tag (specified by the user) is not found in the data.
+
+## `class NotAMapleFileException(MapleDataNotFoundException)`
+
+    This occurs when the file is not a Maple file.
+
+- The file without a "MAPLE" line.
+
+## `class InvalidMapleFileFormatException(NotAMapleFileException)`
+
+    This occurs when the file format is an invalid Maple format.
+
+- The file has a "MAPLE" line, but the format is wrong or broken.
+
+## `class MapleFileEmptyException(NotAMapleFileException)`
+
+    This occurs when the file is empty (No data)
+
+## `class MapleSyntaxException(MapleException)`
+
+    This occurs when the syntax of the MapleTree function (mostly its parameter) is invalid.
+
+## `class MapleTypeException(MapleSyntaxException)`
+
+    This occurs when the user hands the unknown keyword arguments as the `**kwargs` to the MapleTree function.

maplex-3.0.0.dev2/readmes/README_Json.md

@@ -0,0 +1,10 @@
+# MapleJson Class
+
+    MapleJson class is a class library to manage the JSON formatted files.
+
+- You can read a JSON file as a `dict` data.
+- You can write the `dict` data into a file as a JSON formatted string
+- You can save the data as an encrypted data string.
+- You can decrypt the encrypted data.
+
+## Class Initialization

maplex-3.0.0.dev2/readmes/README_Logger.md

@@ -0,0 +1,115 @@
+# Logger Class
+
+    Logger class is a logging object for Python applications. It outputs application logs to log files and to standard output.
+
+## Logger Initialization
+
+```python
+    def __init__(
+            func: str = "",
+            workingDirectory: str | None = None,
+            cmdLogLevel: str | None = None,
+            fileLogLevel: str | None = None,
+            maxLogSize: float | None = None,
+            fileMode: Literal["append", "overwrite", "daily"] | None = None,
+            configFile: str = "config.json",
+            encoding: str | None = None,
+        ) -> None:
+```
+
+|Property|Required|Value|Version|
+|--------|--------|-----|-------|
+|**`func`**||Primary function name||
+|**`workingDirectory`**||Log file output directory||
+|**`cmdLogLevel`**||Terminal output log level||
+|**`fileLogLevel`**||Log file output log level||
+|**`maxLogSize`**||Log file max size (MB)||
+|**`fileMode`**||Logging file mode|`v3.0`|
+|**`configFile`**||Logger configuration file path|`v3.0`|
+|**`encoding`**||Log file encoding|`v3.0`|
+
+    The parameter overwrites the settings configured in `config.mpl`.
+
+## Usage
+
+```python
+from maplex
+
+logger = maplex.getLogger("FunctionName")
+logger.info("Hello there!")
+```
+
+This outputs:
+
+```console
+[INFO ][FunctionName] <module>(4) Hello there!
+```
+
+File output will be:  `AppLog.log`
+
+```log
+(PsNo) yyyy-MM-dd HH:mm:ss.fff [INFO ][FunctionName] <module>(4) Hello there!
+```
+
+### Log Level
+
+- `TRACE`
+- `DEBUG`
+- `INFO`
+- `WARN`
+- `ERROR`
+- `FATAL`
+
+### ShowError function
+
+&nbsp;&nbsp;&nbsp;&nbsp;This outputs the error logs and stuck trace.
+
+Function:
+
+```python
+def ShowError(
+    ex: Exception,
+    message: str | None = None,
+    fatal: bool = False
+)
+```
+
+|Property|Required|Value|
+|--------|--------|-----|
+|**`ex`**|\*|Exception|
+|**`message`**||Custom error message|
+|**`fatal`**||Show error as `FATAL`|
+
+- If `fatal=True`, it outputs log as a `FATAL` log level.
+
+## Settings
+
+- You can configure log settings with a JSON formatted file (default: `config.json`).
+- If the configuration file does not exist, the instance auto-generates the file.
+- Instance uses the parameter values to auto-generate a configuration file, or uses the default value if it was not specified.
+
+Auto-generated configuration file (parameters not specified):
+
+```json
+{
+    "MapleLogger": {
+        "ConsoleLogLevel": "INFO",
+        "FileLogLevel": "INFO",
+        "MaxLogSize": 3.0,
+        "WorkingDirectory": "/path/to/output/logs",
+        "FileEncoding": "utf-8"
+    }
+}
+```
+
+|Key|Value|
+|---|-----|
+|**`ConsoleLogLevel`**|Console log level|
+|**`FileLogLevel`**|File log level|
+|**`MaxLogSize`**|Log file max size (MB)|
+|**`WorkingDirectory`**|Log file output path|
+|**`FileEncoding`**|Log file encoding|
+
+- To disable the log output, set the log level to `NONE`.
+- You can use a `float` number for the file max size (E.g., `2.5` for `2.5MB`)
+- You can also use a `str` for the file max size (E.g., `"3M"`)