MapleX 2.2.0.dev2__tar.gz → 3.0.0__tar.gz

{maplex-2.2.0.dev2 → maplex-3.0.0}/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}/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/PKG-INFO

@@ -0,0 +1,200 @@
+Metadata-Version: 2.4
+Name: MapleX
+Version: 3.0.0
+Summary: A Python library for simple logging, json file operations, Maple file format operations, and console color utilities.
+Author: Ryuji Hazama
+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
+
+![GitHub Tag](https://img.shields.io/github/v/tag/Ryuji-Hazama/MapleTree)
+![GitHub last commit](https://img.shields.io/github/last-commit/Ryuji-Hazama/MapleTree)
+![PyPI - Version](https://img.shields.io/pypi/v/MapleX)
+![PyPI - Downloads](https://img.shields.io/pypi/dm/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 the 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 Best Practice](https://github.com/Ryuji-Hazama/MapleTree/blob/main/readmes/LoggingBestPractice.md)
+
+## MapleJson
+
+&nbsp;&nbsp;&nbsp;&nbsp;MapleJson class is a library class for converting 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 reading, editing, and writeing 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 debugging 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-highlighting 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 [--upgrade] [--break-system-packages]
+```
+
+- `--upgrade` option for upgrade from older version.
+- `--break-system-package` option for Python on Linux OS outside the `venv`. ***This might brak the system Python package dependencies.***
+
+### 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/README.md

@@ -0,0 +1,178 @@
+# MapleX
+
+![GitHub Tag](https://img.shields.io/github/v/tag/Ryuji-Hazama/MapleTree)
+![GitHub last commit](https://img.shields.io/github/last-commit/Ryuji-Hazama/MapleTree)
+![PyPI - Version](https://img.shields.io/pypi/v/MapleX)
+![PyPI - Downloads](https://img.shields.io/pypi/dm/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 the 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 Best Practice](https://github.com/Ryuji-Hazama/MapleTree/blob/main/readmes/LoggingBestPractice.md)
+
+## MapleJson
+
+&nbsp;&nbsp;&nbsp;&nbsp;MapleJson class is a library class for converting 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 reading, editing, and writeing 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 debugging 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-highlighting 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 [--upgrade] [--break-system-packages]
+```
+
+- `--upgrade` option for upgrade from older version.
+- `--break-system-package` option for Python on Linux OS outside the `venv`. ***This might brak the system Python package dependencies.***
+
+### 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}/pyproject.toml

@@ -4,10 +4,9 @@ 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"
+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 = [
@@ -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/readmes/LoggingBestPractice.md

@@ -0,0 +1,20 @@
+# Logging Best Practice
+
+## What Is "Logging"
+
+### The flight recorder of the application
+
+    When you are developing an application, you might experience that your application is crashing silently. Then you will insert a bunch of `print()` lines to determine where the application failed, and what was causing the error. That is a log, and those outputs are showing the exact path of your process, and help you understand what is working correctly, why, and where your code failed after the application halts.
+
+    However, those logs are disappearing when you close the output terminal, or the terminal was automatically closed by the application. That is why you need to output logs to a file like a flight recorder in a black box.
+
+### Four W's of Logging
+
+    Every time the event occurs, the logger should capture the "Four W's" to get the details of the event.
+
+- **When** — When the event occured.
+- **Whrere** — Where the event happened.
+- **What** — What was the event.
+- **Weight** — How seriouc is the event?
+
+### Logging vs `print()`

maplex-3.0.0/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/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.