MapleX 2.2.0__tar.gz → 2.2.0a1__tar.gz

{maplex-2.2.0 → maplex-2.2.0a1}/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 Ryuji Hazama
+Copyright (c) 2025 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/README.md → maplex-2.2.0a1/PKG-INFO

@@ -1,3 +1,24 @@
+Metadata-Version: 2.4
+Name: MapleX
+Version: 2.2.0a1
+Summary: MapleX: A Python library for Maple file format operations, with logging 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/
+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
+
 # :maple_leaf: MapleX :deciduous_tree:
 
     MapleX is a tool set for Maple file format operations, with logging and console color utilities for Python applications.
@@ -5,18 +26,9 @@
     ***You can install the package from pip with the following command.***
 
 ```bash
-pip install MapleX
+pip install maplex
 ```
 
-## Table of Contents
-
-> - [Maple File](#maple-file)
-> - [MapleTree Class](#mapletree-class)
-> - [Logger Class](#logger-class)
-> - [Exceptions](#exceptions)
-> - [Console Colors](#console-colors)
-> - [Install MapleX](#install-maplex)
-
 ## Maple File
 
     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.
@@ -58,15 +70,15 @@ H Data Headers
         H Sub Data Header
             Tags Propaties
             # You can use the same tag in the child header,
-            # which is already used in the parents' header
+            # which is already used in the parent's 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!
+        # Note's main strings for the multi-line data
+        # COMMENTS IN THE "*NOTES" BLOCK WILL BE DELETED WHEN SAVE VALUE!
     E
     H #*
         This is a comment block.
@@ -141,7 +153,7 @@ EOF
 `v2.2.0` or newer
 
 - You can save multi-lined data inside `H *NOTES` block.
-- You must specify the header when you save the notes value.
+- You must specify the header when you save notes value.
 
 E.g.:
 
@@ -302,8 +314,6 @@ EOF
     If `encrypt=True`, the instance decrypts data when it is read, and encrypts data when it is saved.  
     You need to specify the byte key when you use encryption, and the file must be encrypted.
 
-:warning: **The key must be 32 url-safe base64-encoded bytes**
-
 ```python
 mapleFile = MapleTree("FileName.mpl", encrypt=True, key=key)
 ```
@@ -375,32 +385,7 @@ def saveTagLine(
 |**`willSave`**|\*|Save to file flag|
 |**`headers`**||Target headers|
 
-    Outdated from `v2.2.0`
-
-### `saveValue()`
-
-    `v2.2.0` or newer
-
-```python
-def saveValue(
-    tag: str,
-    valueString: any,
-    *headers: str,
-    **kwargs
-) -> bool
-```
-
-|Property|Required|Value|
-|--------|--------|-----|
-|**`tag`**|\*|Target tag|
-|**`value`**|\*|Value to save|
-|**`headers`**||Target headers|
-|**`kwargs`**||Keyword arguments|
-
-    `saveValue` saves a value with a tag in a header block specified by the parameter.
-
-- Set `save=True` to save changes to the file.
-  - Default: `save=False`
+    `saveTagLine` saves a value with a tag in a header block specified by the parameter.
 
 E.g.:
 
@@ -408,7 +393,7 @@ E.g.:
 from maplex import MapleTree
 
 mapleFile = MapleTree("SampleData.mpl", createBaseFile=True)
-mapleFile.saveTagLine("TAG", "VALUE", "FOO", save=True)
+mapleFile.saveTagLine("TAG", "VALUE", True, "FOO")
 
 ```
 
@@ -424,12 +409,12 @@ EOF
 
 #### Update a Buffer Content
 
-    If `save=False` (or not specified), the buffer content will be updated, but no update on physical file content.
+    If `willSave=False`, the buffer content will be updated, but no update on physical file content.
 
 E.g.:
 
 ```python
-mapleFile.saveTagLine("TAG", "NEW VALUE", "FOO")
+mapleFile.saveTagLine("TAG", "NEW VALUE", False, "FOO")
 ```
 
     This code changes the contents on buffer like:
@@ -454,10 +439,10 @@ EOF
 
 #### Update and Save Changes
 
-    If `save=True`, all the changes to the buffer will be saved.
+    If `willSave=True`, all the changes to the buffer will be saved.
 
 ```python
-mapleFile.saveTagLine("BAR", "ANOTHER VALUE", "FOO", save=True)
+mapleFile.saveTagLine("BAR", "ANOTHER VALUE", True, "FOO")
 ```
 
     This code changes the contents in the file like:
@@ -476,10 +461,10 @@ EOF
     If the block and/or the header(s) specified with the parameters do not exist in the data, the function creates the new header block(s) and the tag and saves the value.
 
 ```python
-mapleFile.saveTagLine("TAZ", "NEW HEADER AND TAG", "NEW_HEADER")
+mapleFile.saveTagLine("TAZ", "NEW HEADER AND TAG", False, "NEW_HEADER")
 ```
 
-    This code will change the buffer data like:
+    This code will change the data like:
 
 ```text
 MAPLE
@@ -493,47 +478,48 @@ E
 EOF
 ```
 
-### `deleteTag()`
+### `saveValue()`
+
+    `v2.2.0` or newer
 
 ```python
-def deleteTag(
-    delTag: str,
-    willSave: bool = False,
-    *headers: str
+def saveValue(
+    tag: str,
+    valueString: any,
+    *headers: str,
+    **kwargs
 ) -> bool
 ```
 
 |Property|Required|Value|
 |--------|--------|-----|
-|**`delTag`**|\*|Tag to delete|
-|**`willSave`**||Save to file flag|
+|**`tag`**|\*|Tag to delete|
+|**`value`**|\*|Value to save|
 |**`headers`**||Target headers|
+|**`kwargs`**||Keyword arguments|
 
-    Outdated from `v2.2.0`
-
-### `deleteValue()`
+- Same as `saveTagLine()`
+- Set `save=True` to save changes to the file.
+  - Default: `save=False`
 
-    `v2.2.0` or newer
+### `deleteTag()`
 
 ```python
-def deleteValue(
+def deleteTag(
     delTag: str,
-    *headers: str,
-    **kwargs
+    willSave: bool = False,
+    *headers: str
 ) -> bool
 ```
 
 |Property|Required|Value|
 |--------|--------|-----|
 |**`delTag`**|\*|Tag to delete|
+|**`willSave`**||Save to file flag|
 |**`headers`**||Target headers|
-|**`kwargs`**||Keyword arguments|
 
     Delete a tag and its value.
 
-- Set `save=True` to save changes to the file.
-  - Default: `save=False`
-
 Sample data: `SampleData.mpl`
 
 ```text
@@ -553,7 +539,7 @@ E.g.:
 from maplex import MapleTree
 
 mapleFile = MapleTree("SampleData.mpl")
-mapleFile.deleteTag("BAR", "FOO", save=True)
+mapleFile.deleteTag("BAR", True, "FOO")
 ```
 
     The file data will be changed like:
@@ -568,6 +554,28 @@ E
 EOF
 ```
 
+### `deleteValue()`
+
+    `v2.2.0` or newer
+
+```python
+def deleteValue(
+    delTag: str,
+    *headers: str,
+    **kwargs
+) -> bool
+```
+
+|Property|Required|Value|
+|--------|--------|-----|
+|**`delTag`**|\*|Tag to delete|
+|**`headers`**||Target headers|
+|**`kwargs`**||Keyword arguments|
+
+- Same as `deleteTag()`
+- Set `save=True` to save changes to the file.
+  - Default: `save=False`
+
 ### `getTagValueDict()`
 
 ```python
@@ -662,31 +670,8 @@ def deleteHeader(
 |**`willSave`**||Save to file flag|
 |**`Headers`**||Target headers|
 
-    Outdated from `v2.2.0`
-
-### `removeHeader()`
-
-    `v2.2.0` or newer
-
-```python
-def removeHeader(
-    delHead: str,
-    *headers: str,
-    **kwargs
-) -> bool
-```
-
-|Property|Required|Value|
-|--------|--------|-----|
-|**`delHead`**|\*|Deleting header|
-|**`headers`**||Target headers|
-|**`kwargs`**||Keyword arguments|
-
     This deletes an entire header block and its associated data, including child blocks.
 
-- Set `save=True` for saving data to the file.
-  - Default: `save=False`
-
 Sample data: `SampleData.mpl`
 
 ```text
@@ -711,7 +696,7 @@ E.g.:
 from maplex import MapleTree
 
 mapleTree = MapleTree("SampleData.mpl")
-mapleTree.deleteHeader("FOO", save=True)
+mapleTree.deleteHeader("FOO", True)
 ```
 
     This code changes the data like:
@@ -726,6 +711,28 @@ E
 EOF
 ```
 
+### `removeHeader()`
+
+    `v2.2.0` or newer
+
+```python
+def removeHeader(
+    delHead: str,
+    *headers: str,
+    **kwargs
+) -> bool
+```
+
+|Property|Required|Value|
+|--------|--------|-----|
+|**`delHead`**|\*|Deleting header|
+|**`headers`**||Target headers|
+|**`kwargs`**||Keyword arguments|
+
+- Same as `deleteHeader()`
+- Set `save=True` for save data to the file.
+  - Default: `save=False`
+
 ### `getHeaders()`
 
 ```python
@@ -788,7 +795,7 @@ def saveNotes(
 |**`headers`**|\*|Target headers|
 |**`kwargs`**||Keyword arguments|
 
-    The function saves a string list as a special notes block value. Set `save=True` to save the changes (Default: `save=False`)
+    The function saves string list as a special notes block value. Set `save=True` to save the changes (Default: `save=False`)
 
 E.g.:
 
@@ -800,7 +807,7 @@ stringList = ["Hello", "there!"]
 mapleTree.saveNotes(stringList, "FOO", "BAR", save=True)
 ```
 
-    This code creates a new file that contains the following contents:
+    This code creates a new file contains the following contents:
 
 ```text
 MAPLE
@@ -833,7 +840,7 @@ def saveNote(
 |**`headers`**|\*|Target headers|
 |**`kwargs`**||Keyword arguments|
 
-    The function saves a multi-lined string as a special notes block value. Set `save=True` to save the changes (Default: `save=False`)
+    The function saves multi-lined string as a special notes block value. Set `save=True` to save the changes (Default: `save=False`)
 
 E.g.:
 
@@ -845,7 +852,7 @@ dataString = "This is a\nmulti-lined data."
 mapleTree.saveNotes(dataString, "FOO", "BAR", save=True)
 ```
 
-    This code creates a new file that contains the following contents:
+    This code creates a new file contains the following contents:
 
 ```text
 MAPLE
@@ -874,7 +881,7 @@ def readNotes(
 |--------|--------|-----|
 |**`headers`**|\*|Target headers|
 
-    Read note block value, which is specified by the `headers`, and return as a string list.
+    Read note block value which specified by the `headers` and return as a string list.
 
 Sample data: `SampleData.mpl`
 
@@ -917,7 +924,7 @@ def readNote(
 |--------|--------|-----|
 |**`headers`**|\*|Target headers|
 
-    Read note block value, which specified by the `headers`, and return as a string.
+    Read note block value which specified by the `headers` and return as a string.
 
 Sample data: `SampleData.mpl`
 
@@ -944,7 +951,7 @@ dataString = mapleFile.readNote("FOO", "BAR")
 
 print(dataString)
 # Outputs "This is a
-# multi-lined data."
+# multi-lined data"
 ```
 
 ### `deleteNotes()`
@@ -962,7 +969,7 @@ def deleteNotes(
 |**`headers`**|\*|Target headers|
 |**`kwargs`**||Keyword args|
 
-    Delete note block which specified by the `headers` and return `True` if it succeeds. Set `save=True` to save the changes (Default: `save=False`)
+    Delete note block which specified by the `headers` and return `True` if it success. Set `save=True` to save the changes (Default: `save=False`)
 
 Sample data: `SampleData.mpl`
 
@@ -999,26 +1006,6 @@ E
 EOF
 ```
 
-### `changeEncryptionKey()`
-
-    `v2.2.0` or newer
-
-```python
-def changeEncryptionKey(
-    newKey: bytes,
-    save: bool = False
-    ) -> None
-```
-
-|Property|Required|Value|
-|--------|--------|-----|
-|**`newKey`**|\*|New encryption key|
-|**`save`**||Save to file flag|
-
-    Changing file encryption key. If `save=True`, encrypt the buffer data with the new key and save to the file.
-
-:warning: **The key must be 32 url-safe base64-encoded bytes**
-
 ## Logger Class
 
     Logger is a logging object for Python applications. It outputs application logs to log files and to standard output.
@@ -1051,7 +1038,7 @@ def changeEncryptionKey(
 from maplex import Logger
 
 logger = Logger("FunctionName")
-logger.info("Hello there!")
+logger.Info("Hello there!")
 ```
 
 This outputs:
@@ -1101,9 +1088,8 @@ def ShowError(
 
 - You can configure log settings with `config.mpl`.
 - If `config.mpl` 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 `config.mpl` (parameters not specified):
+Auto-generated `config.mpl`:
 
 ```text
 MAPLE
@@ -1125,8 +1111,8 @@ EOF
 |**`MAX`**|Log file max size (MB)|
 |**`OUT`**|Log file output path|
 
-- 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`)
+- To disable the log output, set log level to `NONE`.
+- You can use a `float` number for the file max size (E.g. `2.5` for `2.5MB`)
 
 ## Exceptions
 
@@ -1136,11 +1122,11 @@ EOF
 
 ### `class MapleFileNotFoundException(MapleException)`
 
-    This occurs when the file that was specified at the instance initialization was not found.
+    This occurs when the file which 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).
+    This occurs when `encrypt=True` at the instance initialization, but the key for encryption is missing (`None` or empty).
 
 ### `class MapleFileLockedException(MapleException)`
 
@@ -1150,10 +1136,6 @@ EOF
 
     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.
@@ -1232,17 +1214,16 @@ EOF
 |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|
 
-## Install MapleX
+## Install maplex :inbox_tray:
 
 ### From PyPI
 
 ```bash
-[python[3] -m] pip install MapleX [--break-system-packages]
+[python[3] -m] pip install maplex [--break-system-packages]
 ```
 
 ### Manual Installation
@@ -1257,9 +1238,3 @@ EOF
 or
 
     Run `python[3] setup.py sdist bdist_wheel`
-
-### Unit test
-
-```bash
-python[3] -m unittest discover -s tests
-```