maci-std


Namemaci-std JSON
Version 1.0.0 PyPI version JSON
download
home_page
SummaryThe easy to use library for your data, configuration, and save files
upload_time2023-12-02 21:55:16
maintainer
docs_urlNone
authoraaronater10
requires_python>=3.7
licenseMIT
keywords maci aaronater10 python py config file export parse text file cfg conf save file config file db database simple configuration alternative safe ini json xml yml data import
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage No coveralls.
            [![Docs](https://raw.githubusercontent.com/aaronater10/maci/main/ext/maci_cover.png)](https://docs.macilib.org/)

# maci
A Python-Styled Serialization Language & Thin Wrapper Library 

![maci-version](https://img.shields.io/pypi/v/maci.svg?label=maci&color=blue)
![maci-language-version](https://img.shields.io/badge/lang-v1.0.0-purple)
[![qa-testing](https://github.com/aaronater10/maci/actions/workflows/maci_qa.yml/badge.svg)](https://github.com/aaronater10/maci/actions/workflows/maci_qa.yml)
![coverage](https://img.shields.io/badge/coverage-100%25-red)
![py-versions](https://img.shields.io/badge/py_versions-3.7_%7C_3.8_%7C_3.9_%7C_3.10_%7C_3.11_%7C_3.12-%23FFD43B)

#

maci is an easy to use library for data serialization. It can parse native python data types from any plain file, which is safer than using an executable .py file for your stored or configuration data. There are useful language features built-in like creating realistic constants for your name/value pairs by locking them, mapping a name to another to follow its value similar to a pointer, and much more.

Its focus is to reduce boilerplate by removing repetitive code implementation, like code written for common file handling, or common libraries used like JSON, YAML, TOML, etc. maci on its own is a pure Python-based library, and I've used variations of this library on projects for many companies and decided I wanted to make a robust and stable public version. It has made common needs less painful, and has solved simplicity in many ways. Hope it helps you

# 🎓 tutorials & docs:
**quick start: [tutorial video](https://docs.macilib.org/watch/quick-start)**

**full tutorials: [all videos](https://docs.macilib.org/watch/full-training-series)**

**docs: [maci docs](https://docs.macilib.org/)**

**changelog: [update history](https://docs.macilib.org/updates/changelog)**

**readme**
\
[installing](#-install-flavors)\
[basic usage: maci](#-basic-usage)\
[basic usage: thin libs](#-basic-usage-thin-libs)\
[exceptions, hints, and built-in tools](#-helpful-extras)\
[performance](#%EF%B8%8F-performance)\
[testing & release](#-testing--release)\
[previous support](#-previous-project-support)


# 🍨 install flavors

**full --> maci, standard library, and 3rd-party packages**
```bash
pip install maci
```
**standard lib --> maci and standard library based packages only**
```bash
pip install maci-std
```
**just maci --> maci package only**
```bash
pip install maci-only
```

[back to top](#maci)

# 📖 basic usage
### maci

Example file "my.file" with maci (Python-styled) data
```python
# Example maci data "my.file"
data1 = 'my data'
data2 = 1
data3 = [1,2,3]
data4 = {'k1': 1}
data5 = True
data6 = (1,2,3)
data7 = {1,2,3}
data8 = 1.0
data9 = None
data10 = b'\ndata\n'
```
#### Load
load maci data from file
```python
maci_data = maci.load('my.file')
maci_data.data1  # access data with attr name
```
load raw data from file
```python
raw_data = maci.loadraw('my.file')  # returns string (default)
```
load attributes names and their values back into your object from file
```python
maci.loadattrs('my.file', my_obj)  # loads in-place
my_obj.data4  # access data in your object with attr name
```
load as dict data from file
```python
dict_data = maci.loaddict('my.file')
dict_data['data3']  # access data as dict key name
```
load maci data from string
```python
maci_data = maci.loadstr('data1 = "data"')
maci_data.data1  # access data with attr name
```
load as dict data from string
```python
dict_data = maci.loadstrdict('data3 = "data"')
dict_data['data3']  # access data as dict key name
```

#### Dump
dump data to file from maci object, dict, or your own object with attrs
```python
maci.dump('my.file', maci_data or dict_data or my_obj)
# creates new file with data formatted as maci syntax
```
dump raw data to file
```python
maci.dumpraw('my.file', 'my data')
# creates new file with data raw as-is to file
```
dump data to string from maci object, dict, or your own object with attrs
```python
str_data = maci.dumpstr(maci_data or dict_data or my_obj)
# returns string with data formatted as maci syntax
```

#### Build
build maci data in code
```python
maci_data = maci.build()
maci_data.data1 = 'my data'
maci_data.data2 = [1,2,3]
maci_data.data3 = 1
maci_data.data4 = True
```
#### In-File Language Features
maci supports varying in-file features. Here are some examples using a file named "my.file":

Lock an attr from re-assignment using a lock glyph
```python
# Example maci data in "my.file"
data1 +l= 'my data'
```
Hard Lock an attr from re-assignment, deletion, and unlocking using a hard lock glyph
```python
# Example maci data in "my.file"
data1 +h= 'my data'
```
Reference and follow another attr's value with an attr (like a pointer) using a map glyph
```python
# Example maci data in "my.file"
data1 = 'my data'
data2 +m= data1
```
Date and time parsing
```python
# Example maci data in "my.file"
# Multiple options -> returns datetime, date, or time object
date_time1 = 2023-03-13 22:06:00
date_time2 = 2023-03-13 22:06:00.50
time_date1 = 22:06:00 2023-03-13
time_date2 = 22:06:00.50 2023-03-13
time1 = 22:06:00
time2 = 22:06:00.50
date = 2023-03-13
date_time_iso8601 = 2023-03-13T22:06:00
```

#### In-Code Language Features
The in-file language features can also be handled in code with a maci object
```python
maci_data.lock_attr('data1')
maci_data.hard_lock_attr('data2')
maci_data.map_attr('data3', 'data4')
```
You may unlock attrs, unmap attrs, and much more with a maci object

Note: if you dump your maci object back to a file, all language features will be retained and represented appropriately in the file

[back to top](#maci)

# 📖 basic usage: thin libs

### json -> based on [json standard library](https://docs.macilib.org/docs/json)
load json data from file
```python
data = maci.jsonload('file.json')
```
load json data from string
```python
data = maci.jsonloadstr('{"k1": "data"}')
```
dump python data to file as json data
```python
maci.jsondump('file.json', data)
```
dump data to string as json data
```python
json_data = maci.jsondumpstr(data)
```
### yaml -> based on [pyyaml framework](https://docs.macilib.org/docs/yaml)
load yaml data from file
```python
data = maci.yamlload('file.yaml')
```
load yaml data from string
```python
data = maci.yamlloadstr('k1: data')
```
dump python data to file as yaml data
```python
maci.yamldump('file.yaml', data)
```
dump data to string as yaml data
```python
yaml_data = maci.yamldumpstr(data)
```
There are also "loadall" and "dumpall" for multiple yaml docs in a file

### toml -> based on [tomli libraries](https://docs.macilib.org/docs/toml)
load toml data from file
```python
data = maci.tomlload('file.toml')
```
load toml data from string
```python
data = maci.tomlloadstr('data1 = "data1"')
```
dump python data to file as toml data
```python
maci.tomldump('file.toml', data)
```
dump data to string as toml data
```python
toml_data = maci.tomldumpstr(data)
```
### ini -> based on [configparser standard library](https://docs.macilib.org/docs/ini)
load ini data from file
```python
configparser_data = maci.iniload('file.ini')
```
dump configparser data to file as ini data
```python
maci.inidump('file.ini', configparser_data)
```
build ini data to configparser data automatically - learn more about [configparser objects](https://docs.python.org/3/library/configparser.html)
```python
configparser_data = maci.inibuildauto({'section1': {'k1': 'value1'}})
```
build configparser data manually - learn more about [configparser objects](https://docs.python.org/3/library/configparser.html)
```python
configparser_data = maci.inibuildmanual()
```

### xml -> based on [xmltodict module & xml etree from standard library](https://docs.macilib.org/docs/xml)
#### Dict (easiest)

load xml data from file as dict
```python
dict_data = maci.xmlloaddict('file.xml')
```
load xml data from string as dict
```python
dict_data = maci.xmlloadstrdict('<tag>data</tag>')
```
dump dict data to file as xml data
```python
maci.xmldumpdict('file.xml', dict_data)
```
dump dict data to string as xml data
```python
xml_data = maci.xmldumpstrdict(dict_data)
```
#### ElementTree - learn more about [element tree objects](https://docs.python.org/3/library/xml.etree.elementtree.html)
load xml data from file as element tree object
```python
et_data = maci.xmlload('file.xml')
```
load xml data from string as element tree object
```python
et_data = maci.xmlloadstr('<tag>data</tag>')
```
dump element tree data to file as xml data
```python
maci.xmldump('file.xml', et_data)
```
dump element tree data to string as xml data
```python
xml_data = maci.xmldumpstr(et_data)
```
build element tree data manually
```python
et_data = maci.xmlbuildmanual()
```

[back to top](#maci)

# 🪄 helpful extras
### exceptions
All exceptions/errors thrown by maci and its thin wrapper libraries are conveniently accessible here:
```python
maci.error
```
Examples of different load exceptions
```python
maci.error.Load
maci.error.JsonLoad
maci.error.YamlLoad
maci.error.TomlLoad
```
To catch/suppress all maci exceptions, use its base exception
```python
maci.error.MaciError
```
### hinting
For type hinting/annotation needs, you can conveniently access the respective object types here:
```python
maci.hint
```
Examples of different hint objects
```python
maci.hint.MaciDataObj
maci.hint.ConfigParser
maci.hint.ElementTree
maci.hint.Element
```
### useful tools
#### cleanformat
format nested data cleanly 
```python
str_data = maci.cleanformat([1,{'k1': 1, 'k2': 2},2])

print(str_data)

Output -->
[
    1,
    {
        'k1': 1,
        'k2': 2,
    },
    2,
]
```
#### pickling
pickle your objects using a non-executable file concept with maci
```python
# Dump to file
maci_data.pickle_data = maci.pickledumpbytes(my_obj)
maci.dump('my.data', maci_data)

# Load back from file
maci_data = maci.load('my.data')
my_obj = maci.pickleloadbytes(maci_data.pickle_data)
```
This is better than having your whole file having the ability to be unpickled, especially if you cannot trust the file's integrity. More on this  from [python pickle docs](https://docs.python.org/3/library/pickle.html). Though this may help improve pickling needs, still use methods to verify integrity of your pickled data if required

#### hashing
Easily generate hash of a file and store hash - default hash is sha256
```python
maci.createfilehash('my.data', 'my.data.hashed')
# always returns string of file hash
```
Now simply compare the hash of the source file to check integrity when needed
```python
maci.comparefilehash('my.data', 'my.data.hashed')
# returns bool if hash is a valid match
```
Create hash of data - default hash is sha256
```python
maci.createhash('data')  # returns string of hash
```

[back to top](#maci)

# ⏳️ performance

Performance tests each library loading **100,000 lines of data** each in their natural usage

Tests are done by loading a file with 100 lines of data 1000 times with the proper file syntax for each library. You may also consider this test about loading 1000 files within the time taken as well

Results vary based on system spec, but you may simulate or prove the same difference in test results for your needs from the "perf" dir in this repo. Results below is running the test 3 times consecutively

**libs tested:** json, pyyaml, tomli, xmltodict, maci

---

**Notes**

*XML ElementTree type and INI Configparser tests were left out for now*

*pyyaml loads much faster using its c-based safe loader, but using the native out of the box methods/functions provided as tests for fairness and potential compatibility issues for needing LibYAML bindings*


---
[//]: <> (chose yml for nice color syntax)
```yml
# Test 1
$ python3 perf_load.py 
Performance tests: "load" - loading file 1000 times with 100 lines of data

xml: 0.225348
json: 0.016725
yaml: 3.625997
toml: 0.23937
maci: 0.807448

# Test 2
$ python3 perf_load.py 
Performance tests: "load" - loading file 1000 times with 100 lines of data

xml: 0.22595
json: 0.016566
yaml: 3.652053
toml: 0.242974
maci: 0.806545

# Test 3
$ python3 perf_load.py 
Performance tests: "load" - loading file 1000 times with 100 lines of data

xml: 0.225579
json: 0.01695
yaml: 3.611955
toml: 0.239593
maci: 0.802843
```

| place | lib |
| ----- | --- |
| 🥇 1st   | json - avg 0.016s |
| 🥈 2nd   | xmltodict - avg 0.225s |
| 🥉 3rd   | tomli - avg 0.240s |
| 4th   | maci - avg 0.805s |
| 5th   | pyyaml - avg 3.630s (4th if using CLoader) |

*Current differences in load time results for 100k lines of data from maci compared to popular or modern libraries*

Looking to continually improve maci's performance and update the results, but so far, not bad for pure python.

[back to top](#maci)

# 🚀 testing & release
### 300+ tests and counting ⚡️

A maci release is only deployed/released if all qa tests pass, and if the revision number is incremented.

All coverage testing must be at 100% or test pipeline will fail (badge is not auto-updated, and just indicates confidence in testing at 100%).

[back to top](#maci)

# ⏪ previous project support
Project maci is derived from an older project called [sfcparse](https://github.com/aaronater10/sfcparse) that is no longer supported, and still provides forward ported support for most of the older API names as a courtesy. sfcparse uses the MIT license, and therefore, maci does not really need to associate itself with that older project, but out of notice for the reason of having the forward ported support is it being mentioned if desiring to migrate.

Reason for sfcparse's deprecation was merely for desire of re-branding and scrapping the old to make usage simpler and anew, thus, maci.

Though maci does support the older API names as a courtesy, some names being attempted to use may throw exceptions. Also, functionality in a lot of the forward connected API names may require different parameter positional args or kwargs. See these files for API matched names and where they point to

function names: [\_\_init\_\_.py](https://github.com/aaronater10/maci/blob/main/src/maci/__init__.py) under \_\_getattr\_\_

exception names: [error.py](https://github.com/aaronater10/maci/blob/main/src/maci/error.py) under \_\_getattr\_\_

[back to top](#maci)

            

Raw data

            {
    "_id": null,
    "home_page": "",
    "name": "maci-std",
    "maintainer": "",
    "docs_url": null,
    "requires_python": ">=3.7",
    "maintainer_email": "",
    "keywords": "maci,aaronater10,python,py,config,file,export,parse,text file,cfg,conf,save file,config file,db,database,simple,configuration,alternative,safe,ini,json,xml,yml,data,import",
    "author": "aaronater10",
    "author_email": "dev_admin@dunnts.com",
    "download_url": "https://files.pythonhosted.org/packages/36/bb/dee2e14cf7980b6da8f43355b57aae8b983a36881f10d3ae1f05c42d7138/maci-std-1.0.0.tar.gz",
    "platform": null,
    "description": "[![Docs](https://raw.githubusercontent.com/aaronater10/maci/main/ext/maci_cover.png)](https://docs.macilib.org/)\n\n# maci\nA Python-Styled Serialization Language & Thin Wrapper Library \n\n![maci-version](https://img.shields.io/pypi/v/maci.svg?label=maci&color=blue)\n![maci-language-version](https://img.shields.io/badge/lang-v1.0.0-purple)\n[![qa-testing](https://github.com/aaronater10/maci/actions/workflows/maci_qa.yml/badge.svg)](https://github.com/aaronater10/maci/actions/workflows/maci_qa.yml)\n![coverage](https://img.shields.io/badge/coverage-100%25-red)\n![py-versions](https://img.shields.io/badge/py_versions-3.7_%7C_3.8_%7C_3.9_%7C_3.10_%7C_3.11_%7C_3.12-%23FFD43B)\n\n#\n\nmaci is an easy to use library for data serialization. It can parse native python data types from any plain file, which is safer than using an executable .py file for your stored or configuration data. There are useful language features built-in like creating realistic constants for your name/value pairs by locking them, mapping a name to another to follow its value similar to a pointer, and much more.\n\nIts focus is to reduce boilerplate by removing repetitive code implementation, like code written for common file handling, or common libraries used like JSON, YAML, TOML, etc. maci on its own is a pure Python-based library, and I've used variations of this library on projects for many companies and decided I wanted to make a robust and stable public version. It has made common needs less painful, and has solved simplicity in many ways. Hope it helps you\n\n# \ud83c\udf93 tutorials & docs:\n**quick start: [tutorial video](https://docs.macilib.org/watch/quick-start)**\n\n**full tutorials: [all videos](https://docs.macilib.org/watch/full-training-series)**\n\n**docs: [maci docs](https://docs.macilib.org/)**\n\n**changelog: [update history](https://docs.macilib.org/updates/changelog)**\n\n**readme**\n\\\n[installing](#-install-flavors)\\\n[basic usage: maci](#-basic-usage)\\\n[basic usage: thin libs](#-basic-usage-thin-libs)\\\n[exceptions, hints, and built-in tools](#-helpful-extras)\\\n[performance](#%EF%B8%8F-performance)\\\n[testing & release](#-testing--release)\\\n[previous support](#-previous-project-support)\n\n\n# \ud83c\udf68 install flavors\n\n**full --> maci, standard library, and 3rd-party packages**\n```bash\npip install maci\n```\n**standard lib --> maci and standard library based packages only**\n```bash\npip install maci-std\n```\n**just maci --> maci package only**\n```bash\npip install maci-only\n```\n\n[back to top](#maci)\n\n# \ud83d\udcd6 basic usage\n### maci\n\nExample file \"my.file\" with maci (Python-styled) data\n```python\n# Example maci data \"my.file\"\ndata1 = 'my data'\ndata2 = 1\ndata3 = [1,2,3]\ndata4 = {'k1': 1}\ndata5 = True\ndata6 = (1,2,3)\ndata7 = {1,2,3}\ndata8 = 1.0\ndata9 = None\ndata10 = b'\\ndata\\n'\n```\n#### Load\nload maci data from file\n```python\nmaci_data = maci.load('my.file')\nmaci_data.data1  # access data with attr name\n```\nload raw data from file\n```python\nraw_data = maci.loadraw('my.file')  # returns string (default)\n```\nload attributes names and their values back into your object from file\n```python\nmaci.loadattrs('my.file', my_obj)  # loads in-place\nmy_obj.data4  # access data in your object with attr name\n```\nload as dict data from file\n```python\ndict_data = maci.loaddict('my.file')\ndict_data['data3']  # access data as dict key name\n```\nload maci data from string\n```python\nmaci_data = maci.loadstr('data1 = \"data\"')\nmaci_data.data1  # access data with attr name\n```\nload as dict data from string\n```python\ndict_data = maci.loadstrdict('data3 = \"data\"')\ndict_data['data3']  # access data as dict key name\n```\n\n#### Dump\ndump data to file from maci object, dict, or your own object with attrs\n```python\nmaci.dump('my.file', maci_data or dict_data or my_obj)\n# creates new file with data formatted as maci syntax\n```\ndump raw data to file\n```python\nmaci.dumpraw('my.file', 'my data')\n# creates new file with data raw as-is to file\n```\ndump data to string from maci object, dict, or your own object with attrs\n```python\nstr_data = maci.dumpstr(maci_data or dict_data or my_obj)\n# returns string with data formatted as maci syntax\n```\n\n#### Build\nbuild maci data in code\n```python\nmaci_data = maci.build()\nmaci_data.data1 = 'my data'\nmaci_data.data2 = [1,2,3]\nmaci_data.data3 = 1\nmaci_data.data4 = True\n```\n#### In-File Language Features\nmaci supports varying in-file features. Here are some examples using a file named \"my.file\":\n\nLock an attr from re-assignment using a lock glyph\n```python\n# Example maci data in \"my.file\"\ndata1 +l= 'my data'\n```\nHard Lock an attr from re-assignment, deletion, and unlocking using a hard lock glyph\n```python\n# Example maci data in \"my.file\"\ndata1 +h= 'my data'\n```\nReference and follow another attr's value with an attr (like a pointer) using a map glyph\n```python\n# Example maci data in \"my.file\"\ndata1 = 'my data'\ndata2 +m= data1\n```\nDate and time parsing\n```python\n# Example maci data in \"my.file\"\n# Multiple options -> returns datetime, date, or time object\ndate_time1 = 2023-03-13 22:06:00\ndate_time2 = 2023-03-13 22:06:00.50\ntime_date1 = 22:06:00 2023-03-13\ntime_date2 = 22:06:00.50 2023-03-13\ntime1 = 22:06:00\ntime2 = 22:06:00.50\ndate = 2023-03-13\ndate_time_iso8601 = 2023-03-13T22:06:00\n```\n\n#### In-Code Language Features\nThe in-file language features can also be handled in code with a maci object\n```python\nmaci_data.lock_attr('data1')\nmaci_data.hard_lock_attr('data2')\nmaci_data.map_attr('data3', 'data4')\n```\nYou may unlock attrs, unmap attrs, and much more with a maci object\n\nNote: if you dump your maci object back to a file, all language features will be retained and represented appropriately in the file\n\n[back to top](#maci)\n\n# \ud83d\udcd6 basic usage: thin libs\n\n### json -> based on [json standard library](https://docs.macilib.org/docs/json)\nload json data from file\n```python\ndata = maci.jsonload('file.json')\n```\nload json data from string\n```python\ndata = maci.jsonloadstr('{\"k1\": \"data\"}')\n```\ndump python data to file as json data\n```python\nmaci.jsondump('file.json', data)\n```\ndump data to string as json data\n```python\njson_data = maci.jsondumpstr(data)\n```\n### yaml -> based on [pyyaml framework](https://docs.macilib.org/docs/yaml)\nload yaml data from file\n```python\ndata = maci.yamlload('file.yaml')\n```\nload yaml data from string\n```python\ndata = maci.yamlloadstr('k1: data')\n```\ndump python data to file as yaml data\n```python\nmaci.yamldump('file.yaml', data)\n```\ndump data to string as yaml data\n```python\nyaml_data = maci.yamldumpstr(data)\n```\nThere are also \"loadall\" and \"dumpall\" for multiple yaml docs in a file\n\n### toml -> based on [tomli libraries](https://docs.macilib.org/docs/toml)\nload toml data from file\n```python\ndata = maci.tomlload('file.toml')\n```\nload toml data from string\n```python\ndata = maci.tomlloadstr('data1 = \"data1\"')\n```\ndump python data to file as toml data\n```python\nmaci.tomldump('file.toml', data)\n```\ndump data to string as toml data\n```python\ntoml_data = maci.tomldumpstr(data)\n```\n### ini -> based on [configparser standard library](https://docs.macilib.org/docs/ini)\nload ini data from file\n```python\nconfigparser_data = maci.iniload('file.ini')\n```\ndump configparser data to file as ini data\n```python\nmaci.inidump('file.ini', configparser_data)\n```\nbuild ini data to configparser data automatically - learn more about [configparser objects](https://docs.python.org/3/library/configparser.html)\n```python\nconfigparser_data = maci.inibuildauto({'section1': {'k1': 'value1'}})\n```\nbuild configparser data manually - learn more about [configparser objects](https://docs.python.org/3/library/configparser.html)\n```python\nconfigparser_data = maci.inibuildmanual()\n```\n\n### xml -> based on [xmltodict module & xml etree from standard library](https://docs.macilib.org/docs/xml)\n#### Dict (easiest)\n\nload xml data from file as dict\n```python\ndict_data = maci.xmlloaddict('file.xml')\n```\nload xml data from string as dict\n```python\ndict_data = maci.xmlloadstrdict('<tag>data</tag>')\n```\ndump dict data to file as xml data\n```python\nmaci.xmldumpdict('file.xml', dict_data)\n```\ndump dict data to string as xml data\n```python\nxml_data = maci.xmldumpstrdict(dict_data)\n```\n#### ElementTree - learn more about [element tree objects](https://docs.python.org/3/library/xml.etree.elementtree.html)\nload xml data from file as element tree object\n```python\net_data = maci.xmlload('file.xml')\n```\nload xml data from string as element tree object\n```python\net_data = maci.xmlloadstr('<tag>data</tag>')\n```\ndump element tree data to file as xml data\n```python\nmaci.xmldump('file.xml', et_data)\n```\ndump element tree data to string as xml data\n```python\nxml_data = maci.xmldumpstr(et_data)\n```\nbuild element tree data manually\n```python\net_data = maci.xmlbuildmanual()\n```\n\n[back to top](#maci)\n\n# \ud83e\ude84 helpful extras\n### exceptions\nAll exceptions/errors thrown by maci and its thin wrapper libraries are conveniently accessible here:\n```python\nmaci.error\n```\nExamples of different load exceptions\n```python\nmaci.error.Load\nmaci.error.JsonLoad\nmaci.error.YamlLoad\nmaci.error.TomlLoad\n```\nTo catch/suppress all maci exceptions, use its base exception\n```python\nmaci.error.MaciError\n```\n### hinting\nFor type hinting/annotation needs, you can conveniently access the respective object types here:\n```python\nmaci.hint\n```\nExamples of different hint objects\n```python\nmaci.hint.MaciDataObj\nmaci.hint.ConfigParser\nmaci.hint.ElementTree\nmaci.hint.Element\n```\n### useful tools\n#### cleanformat\nformat nested data cleanly \n```python\nstr_data = maci.cleanformat([1,{'k1': 1, 'k2': 2},2])\n\nprint(str_data)\n\nOutput -->\n[\n    1,\n    {\n        'k1': 1,\n        'k2': 2,\n    },\n    2,\n]\n```\n#### pickling\npickle your objects using a non-executable file concept with maci\n```python\n# Dump to file\nmaci_data.pickle_data = maci.pickledumpbytes(my_obj)\nmaci.dump('my.data', maci_data)\n\n# Load back from file\nmaci_data = maci.load('my.data')\nmy_obj = maci.pickleloadbytes(maci_data.pickle_data)\n```\nThis is better than having your whole file having the ability to be unpickled, especially if you cannot trust the file's integrity. More on this  from [python pickle docs](https://docs.python.org/3/library/pickle.html). Though this may help improve pickling needs, still use methods to verify integrity of your pickled data if required\n\n#### hashing\nEasily generate hash of a file and store hash - default hash is sha256\n```python\nmaci.createfilehash('my.data', 'my.data.hashed')\n# always returns string of file hash\n```\nNow simply compare the hash of the source file to check integrity when needed\n```python\nmaci.comparefilehash('my.data', 'my.data.hashed')\n# returns bool if hash is a valid match\n```\nCreate hash of data - default hash is sha256\n```python\nmaci.createhash('data')  # returns string of hash\n```\n\n[back to top](#maci)\n\n# \u23f3\ufe0f performance\n\nPerformance tests each library loading **100,000 lines of data** each in their natural usage\n\nTests are done by loading a file with 100 lines of data 1000 times with the proper file syntax for each library. You may also consider this test about loading 1000 files within the time taken as well\n\nResults vary based on system spec, but you may simulate or prove the same difference in test results for your needs from the \"perf\" dir in this repo. Results below is running the test 3 times consecutively\n\n**libs tested:** json, pyyaml, tomli, xmltodict, maci\n\n---\n\n**Notes**\n\n*XML ElementTree type and INI Configparser tests were left out for now*\n\n*pyyaml loads much faster using its c-based safe loader, but using the native out of the box methods/functions provided as tests for fairness and potential compatibility issues for needing LibYAML bindings*\n\n\n---\n[//]: <> (chose yml for nice color syntax)\n```yml\n# Test 1\n$ python3 perf_load.py \nPerformance tests: \"load\" - loading file 1000 times with 100 lines of data\n\nxml: 0.225348\njson: 0.016725\nyaml: 3.625997\ntoml: 0.23937\nmaci: 0.807448\n\n# Test 2\n$ python3 perf_load.py \nPerformance tests: \"load\" - loading file 1000 times with 100 lines of data\n\nxml: 0.22595\njson: 0.016566\nyaml: 3.652053\ntoml: 0.242974\nmaci: 0.806545\n\n# Test 3\n$ python3 perf_load.py \nPerformance tests: \"load\" - loading file 1000 times with 100 lines of data\n\nxml: 0.225579\njson: 0.01695\nyaml: 3.611955\ntoml: 0.239593\nmaci: 0.802843\n```\n\n| place | lib |\n| ----- | --- |\n| \ud83e\udd47 1st   | json - avg 0.016s |\n| \ud83e\udd48 2nd   | xmltodict - avg 0.225s |\n| \ud83e\udd49 3rd   | tomli - avg 0.240s |\n| 4th   | maci - avg 0.805s |\n| 5th   | pyyaml - avg 3.630s (4th if using CLoader) |\n\n*Current differences in load time results for 100k lines of data from maci compared to popular or modern libraries*\n\nLooking to continually improve maci's performance and update the results, but so far, not bad for pure python.\n\n[back to top](#maci)\n\n# \ud83d\ude80 testing & release\n### 300+ tests and counting \u26a1\ufe0f\n\nA maci release is only deployed/released if all qa tests pass, and if the revision number is incremented.\n\nAll coverage testing must be at 100% or test pipeline will fail (badge is not auto-updated, and just indicates confidence in testing at 100%).\n\n[back to top](#maci)\n\n# \u23ea previous project support\nProject maci is derived from an older project called [sfcparse](https://github.com/aaronater10/sfcparse) that is no longer supported, and still provides forward ported support for most of the older API names as a courtesy. sfcparse uses the MIT license, and therefore, maci does not really need to associate itself with that older project, but out of notice for the reason of having the forward ported support is it being mentioned if desiring to migrate.\n\nReason for sfcparse's deprecation was merely for desire of re-branding and scrapping the old to make usage simpler and anew, thus, maci.\n\nThough maci does support the older API names as a courtesy, some names being attempted to use may throw exceptions. Also, functionality in a lot of the forward connected API names may require different parameter positional args or kwargs. See these files for API matched names and where they point to\n\nfunction names: [\\_\\_init\\_\\_.py](https://github.com/aaronater10/maci/blob/main/src/maci/__init__.py) under \\_\\_getattr\\_\\_\n\nexception names: [error.py](https://github.com/aaronater10/maci/blob/main/src/maci/error.py) under \\_\\_getattr\\_\\_\n\n[back to top](#maci)\n",
    "bugtrack_url": null,
    "license": "MIT",
    "summary": "The easy to use library for your data, configuration, and save files",
    "version": "1.0.0",
    "project_urls": {
        "Bugs": "https://github.com/aaronater10/maci/issues",
        "CI": "https://github.com/aaronater10/maci/actions",
        "Code": "https://github.com/aaronater10/maci",
        "Docs": "https://docs.macilib.org"
    },
    "split_keywords": [
        "maci",
        "aaronater10",
        "python",
        "py",
        "config",
        "file",
        "export",
        "parse",
        "text file",
        "cfg",
        "conf",
        "save file",
        "config file",
        "db",
        "database",
        "simple",
        "configuration",
        "alternative",
        "safe",
        "ini",
        "json",
        "xml",
        "yml",
        "data",
        "import"
    ],
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "d954e5bfe5ae72ba1191e2acecbad31811b1e4017ca03958a8d10bb4e5c183bf",
                "md5": "c580c87d954768d97c221278f027e02f",
                "sha256": "6670ee8b34a2c452ba08b85cb5b6d8e6864c04d0bce49deaafe00087bc423158"
            },
            "downloads": -1,
            "filename": "maci_std-1.0.0-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "c580c87d954768d97c221278f027e02f",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": ">=3.7",
            "size": 60112,
            "upload_time": "2023-12-02T21:55:14",
            "upload_time_iso_8601": "2023-12-02T21:55:14.998478Z",
            "url": "https://files.pythonhosted.org/packages/d9/54/e5bfe5ae72ba1191e2acecbad31811b1e4017ca03958a8d10bb4e5c183bf/maci_std-1.0.0-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "36bbdee2e14cf7980b6da8f43355b57aae8b983a36881f10d3ae1f05c42d7138",
                "md5": "275ffe7581a88a81451ae48de85cb8fd",
                "sha256": "dd1ea51f7677669b34443b76fb0ee1965b5dce38246024f0ae01a27e406d353e"
            },
            "downloads": -1,
            "filename": "maci-std-1.0.0.tar.gz",
            "has_sig": false,
            "md5_digest": "275ffe7581a88a81451ae48de85cb8fd",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.7",
            "size": 44498,
            "upload_time": "2023-12-02T21:55:16",
            "upload_time_iso_8601": "2023-12-02T21:55:16.878423Z",
            "url": "https://files.pythonhosted.org/packages/36/bb/dee2e14cf7980b6da8f43355b57aae8b983a36881f10d3ae1f05c42d7138/maci-std-1.0.0.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2023-12-02 21:55:16",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "github_user": "aaronater10",
    "github_project": "maci",
    "travis_ci": false,
    "coveralls": false,
    "github_actions": true,
    "lcname": "maci-std"
}
        
Elapsed time: 0.19198s