ft3 0.0.1__tar.gz

ft3-0.0.1/LICENSE

@@ -0,0 +1,165 @@
+                   GNU LESSER GENERAL PUBLIC LICENSE
+                       Version 3, 29 June 2007
+
+ Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/>
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+
+  This version of the GNU Lesser General Public License incorporates
+the terms and conditions of version 3 of the GNU General Public
+License, supplemented by the additional permissions listed below.
+
+  0. Additional Definitions.
+
+  As used herein, "this License" refers to version 3 of the GNU Lesser
+General Public License, and the "GNU GPL" refers to version 3 of the GNU
+General Public License.
+
+  "The Library" refers to a covered work governed by this License,
+other than an Application or a Combined Work as defined below.
+
+  An "Application" is any work that makes use of an interface provided
+by the Library, but which is not otherwise based on the Library.
+Defining a subclass of a class defined by the Library is deemed a mode
+of using an interface provided by the Library.
+
+  A "Combined Work" is a work produced by combining or linking an
+Application with the Library.  The particular version of the Library
+with which the Combined Work was made is also called the "Linked
+Version".
+
+  The "Minimal Corresponding Source" for a Combined Work means the
+Corresponding Source for the Combined Work, excluding any source code
+for portions of the Combined Work that, considered in isolation, are
+based on the Application, and not on the Linked Version.
+
+  The "Corresponding Application Code" for a Combined Work means the
+object code and/or source code for the Application, including any data
+and utility programs needed for reproducing the Combined Work from the
+Application, but excluding the System Libraries of the Combined Work.
+
+  1. Exception to Section 3 of the GNU GPL.
+
+  You may convey a covered work under sections 3 and 4 of this License
+without being bound by section 3 of the GNU GPL.
+
+  2. Conveying Modified Versions.
+
+  If you modify a copy of the Library, and, in your modifications, a
+facility refers to a function or data to be supplied by an Application
+that uses the facility (other than as an argument passed when the
+facility is invoked), then you may convey a copy of the modified
+version:
+
+   a) under this License, provided that you make a good faith effort to
+   ensure that, in the event an Application does not supply the
+   function or data, the facility still operates, and performs
+   whatever part of its purpose remains meaningful, or
+
+   b) under the GNU GPL, with none of the additional permissions of
+   this License applicable to that copy.
+
+  3. Object Code Incorporating Material from Library Header Files.
+
+  The object code form of an Application may incorporate material from
+a header file that is part of the Library.  You may convey such object
+code under terms of your choice, provided that, if the incorporated
+material is not limited to numerical parameters, data structure
+layouts and accessors, or small macros, inline functions and templates
+(ten or fewer lines in length), you do both of the following:
+
+   a) Give prominent notice with each copy of the object code that the
+   Library is used in it and that the Library and its use are
+   covered by this License.
+
+   b) Accompany the object code with a copy of the GNU GPL and this license
+   document.
+
+  4. Combined Works.
+
+  You may convey a Combined Work under terms of your choice that,
+taken together, effectively do not restrict modification of the
+portions of the Library contained in the Combined Work and reverse
+engineering for debugging such modifications, if you also do each of
+the following:
+
+   a) Give prominent notice with each copy of the Combined Work that
+   the Library is used in it and that the Library and its use are
+   covered by this License.
+
+   b) Accompany the Combined Work with a copy of the GNU GPL and this license
+   document.
+
+   c) For a Combined Work that displays copyright notices during
+   execution, include the copyright notice for the Library among
+   these notices, as well as a reference directing the user to the
+   copies of the GNU GPL and this license document.
+
+   d) Do one of the following:
+
+       0) Convey the Minimal Corresponding Source under the terms of this
+       License, and the Corresponding Application Code in a form
+       suitable for, and under terms that permit, the user to
+       recombine or relink the Application with a modified version of
+       the Linked Version to produce a modified Combined Work, in the
+       manner specified by section 6 of the GNU GPL for conveying
+       Corresponding Source.
+
+       1) Use a suitable shared library mechanism for linking with the
+       Library.  A suitable mechanism is one that (a) uses at run time
+       a copy of the Library already present on the user's computer
+       system, and (b) will operate properly with a modified version
+       of the Library that is interface-compatible with the Linked
+       Version.
+
+   e) Provide Installation Information, but only if you would otherwise
+   be required to provide such information under section 6 of the
+   GNU GPL, and only to the extent that such information is
+   necessary to install and execute a modified version of the
+   Combined Work produced by recombining or relinking the
+   Application with a modified version of the Linked Version. (If
+   you use option 4d0, the Installation Information must accompany
+   the Minimal Corresponding Source and Corresponding Application
+   Code. If you use option 4d1, you must provide the Installation
+   Information in the manner specified by section 6 of the GNU GPL
+   for conveying Corresponding Source.)
+
+  5. Combined Libraries.
+
+  You may place library facilities that are a work based on the
+Library side by side in a single library together with other library
+facilities that are not Applications and are not covered by this
+License, and convey such a combined library under terms of your
+choice, if you do both of the following:
+
+   a) Accompany the combined library with a copy of the same work based
+   on the Library, uncombined with any other library facilities,
+   conveyed under the terms of this License.
+
+   b) Give prominent notice with the combined library that part of it
+   is a work based on the Library, and explaining where to find the
+   accompanying uncombined form of the same work.
+
+  6. Revised Versions of the GNU Lesser General Public License.
+
+  The Free Software Foundation may publish revised and/or new versions
+of the GNU Lesser General Public License from time to time. Such new
+versions will be similar in spirit to the present version, but may
+differ in detail to address new problems or concerns.
+
+  Each version is given a distinguishing version number. If the
+Library as you received it specifies that a certain numbered version
+of the GNU Lesser General Public License "or any later version"
+applies to it, you have the option of following the terms and
+conditions either of that published version or of any later version
+published by the Free Software Foundation. If the Library as you
+received it does not specify a version number of the GNU Lesser
+General Public License, you may choose any version of the GNU Lesser
+General Public License ever published by the Free Software Foundation.
+
+  If the Library as you received it specifies that a proxy can decide
+whether future versions of the GNU Lesser General Public License shall
+apply, that proxy's public statement of acceptance of any version is
+permanent authorization for you to choose that version for the
+Library.

ft3-0.0.1/PKG-INFO

@@ -0,0 +1,443 @@
+Metadata-Version: 2.1
+Name: ft3
+Version: 0.0.1
+Summary: Zero-dependency Python framework for object oriented development.
+Author-email: Dan <dan@1howardcapital.com>
+Maintainer-email: Dan <dan@1howardcapital.com>
+Project-URL: Documentation, https://ft3.readthedocs.io/en/stable/ft3.html
+Project-URL: Homepage, https://ft3.readthedocs.io/en/stable/
+Project-URL: Repository, https://github.com/dan1hc/ft3.git
+Project-URL: Issues, https://github.com/dan1hc/ft3/issues
+Project-URL: Changelog, https://github.com/dan1hc/ft3/blob/main/CHANGELOG.md
+Keywords: dataclasses,ft3,framework,openapi,rest,swagger
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: OSI Approved :: GNU Library or Lesser General Public License (LGPL)
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: typing_extensions; python_version < "3.11"
+Provides-Extra: develop
+Requires-Dist: mypy==1.11.*; extra == "develop"
+Requires-Dist: pre-commit==3.7.*; extra == "develop"
+Requires-Dist: coverage==7.6.*; extra == "develop"
+Requires-Dist: pytest==8.3.*; extra == "develop"
+Requires-Dist: pytest-cov==5.0.*; extra == "develop"
+Requires-Dist: ruff==0.5.*; extra == "develop"
+Requires-Dist: commonmark==0.9.*; extra == "develop"
+Requires-Dist: sphinx==7.*; extra == "develop"
+Provides-Extra: docs
+Requires-Dist: commonmark==0.9.*; extra == "docs"
+Requires-Dist: sphinx==7.*; extra == "docs"
+
+# [![banner](https://1howardcapital.s3.amazonaws.com/images/ft3/banner.png)](https://ft3.readthedocs.io)
+
+[![MinVersion](https://img.shields.io/python/required-version-toml?tomlFilePath=https://raw.githubusercontent.com/dan1hc/ft3/main/pyproject.toml&color=gold)](https://pypi.org/project/ft3)
+[![PyVersions](https://img.shields.io/pypi/pyversions/ft3?color=brightgreen)](https://pypi.org/project/ft3)
+[![readthedocs](https://readthedocs.org/projects/ft3/badge)](https://ft3.readthedocs.io)
+[![CI](https://github.com/dan1hc/ft3/actions/workflows/main.yml/badge.svg?branch=main&event=push)](https://github.com/dan1hc/ft3/actions)
+[![codeql](https://github.com/dan1hc/ft3/workflows/codeql/badge.svg)](https://github.com/dan1hc/ft3/actions/workflows/codeql.yml)
+[![coverage](https://img.shields.io/badge/dynamic/toml?url=https://raw.githubusercontent.com/dan1hc/ft3/main/pyproject.toml&query=tool.coverage.report.fail_under&label=coverage&suffix=%25&color=brightgreen)](https://github.com/dan1hc/ft3/actions)
+[![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white)](https://github.com/pre-commit/pre-commit)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+[![mypy](https://www.mypy-lang.org/static/mypy_badge.svg)](http://mypy-lang.org/)
+[![PyPI](https://img.shields.io/pypi/v/ft3?color=blue)](https://pypi.org/project/ft3)
+[![License](https://img.shields.io/pypi/l/ft3?color=blue)](https://www.gnu.org/licenses/lgpl-3.0)
+
+# Overview
+
+**Author:** dan@1howardcapital.com | daniel.dube@annalect.com
+
+**Summary:** Zero-dependency python framework for object oriented development.
+Implement _once_, document _once_, in _one_ place.
+
+> With ft3, you will quickly learn established best practice...
+> or face the consequences of runtime errors that will break your code
+> if you deviate from it.
+>
+> Experienced python engineers will find a framework
+> that expects and rewards intuitive magic method usage,
+> consistent type annotations, and robust docstrings.
+>
+> Implement _pythonically_ with ft3 and you will only ever need to:
+> implement _once_, document _once_, in _one_ place.
+
+---
+
+## Mission Statement
+
+Ultimately, ft3 seeks to capture and abstract all recurring patterns in
+application development with known, optimal implementations, so engineers
+can focus more on clever implementation of application-specific logic and good
+documentation than on things like how to query X database most efficiently,
+whether or not everything important is being logged correctly, where to
+put what documentation, and how to implement an effective change management
+scheme with git in the first place.
+
+## Getting Started
+
+### Installation
+
+```bash
+pip install ft3
+```
+
+### Basic Usage
+
+```py
+import ft3
+
+
+class Pet(ft3.Object):
+    """A pet."""
+
+    id_: ft3.Field[int]
+    name: ft3.Field[str]
+    type_: ft3.Field[str] = {
+        'default': 'dog',
+        'enum': ['cat', 'dog'],
+        'nullable': False,
+        'required': True,
+        }
+    is_tail_wagging: ft3.Field[bool] = ft3.Field(
+        default=True,
+        enum=[True, False],
+        nullable=False,
+        required=True,
+        )
+
+```
+
+## Best Practice - Guard Rails at a Bowling Alley
+
+ft3 has been designed from the outset to teach best practice to less
+experienced python engineers, without compromising their ability to
+make effective and timely contributions.
+
+> To ft3, it is more important developers are able to make
+> effective contributions while learning, rather than sacrifice
+> any contribution at all until the developer fully understands
+> why something that could be done many ways should only ever
+> be done one way.
+
+#### Exceptions
+
+This is achieved primarily through the raising of exceptions.
+In many cases, if a developer inadvertently deviaties from a known
+best practice, ft3 will raise a code-breaking error (informing
+the developer of the violation) until the developer implements
+the optimal solution.
+
+#### Logging
+
+ft3 will commandeer your application's log.
+
+* It will automatically redact sensitive data inadvertently introduced
+to your log stream that would have made your application fail audits.
+* It will intercept, warn once, and subsequently silence print statements,
+debug statements, and other errant attempts at logging information in ways
+certain to introduce a known anti-pattern, vulnerability, or otherwise
+pollute your log stream.
+
+> In short, if ft3 raises an error or otherwise does not support
+> the thing you are trying to do: it is because the way in which you
+> are trying to do it contains at least one anti-pattern to a known,
+> optimal solution.
+
+## Example Usage
+
+```py
+import ft3
+
+
+class Flea(ft3.Object):
+    """A nuisance."""
+
+    name: ft3.Field[str] = 'FLEA'
+
+
+class Pet(ft3.Object):
+    """A pet."""
+
+    id_: ft3.Field[str]
+    _alternate_id: ft3.Field[int]
+
+    name: ft3.Field[str]
+    type_: ft3.Field[str] = {
+        'default': 'dog',
+        'enum': ['cat', 'dog'],
+        'nullable': False,
+        'required': True,
+        }
+
+    in_: ft3.Field[str]
+    is_tail_wagging: ft3.Field[bool] = ft3.Field(
+        default=True,
+        enum=[True, False],
+        nullable=False,
+        required=True,
+        )
+
+    fleas: ft3.Field[list[Flea]] = [
+        Flea(name='flea1'),
+        Flea(name='flea2')
+        ]
+
+
+# Automatic case handling.
+request_body = {
+    'id': 'abc123',
+    'alternateId': 123,
+    'name': 'Bob',
+    'type': 'dog',
+    'in': 'timeout',
+    'isTailWagging': False
+    }
+pet = Pet(request_body)
+
+assert pet.is_snake_case == Pet.is_snake_case is True
+assert pet.is_camel_case == Pet.is_camel_case is False
+assert pet['alternate_id'] == pet._alternate_id == request_body['alternateId']
+assert dict(pet) == {k: v for k, v in pet.items()} == pet.to_dict()
+
+# Automatic, mutation-safe "default factory".
+dog = Pet(id='abc321', alternate_id=321, name='Fido')
+assert pet.fleas[0] is not dog.fleas[0]
+
+# Automatic memory optimization.
+assert Flea().__sizeof__() == (len(Flea.__slots__) * 8) + 16 == 32
+
+class Flet(Flea, Pet):
+    ...
+
+class Pea(Pet, Flea):
+    ...
+
+assert Flet().__sizeof__() == (len(Flet.__base__.__slots__) * 8) + 16 == 80
+assert Pea().__sizeof__() == (len(Pea.__base__.__slots__) * 8) + 16 == 80
+assert Flet().name == 'FLEA' != Pea().name
+
+# Intuitive, database agnostic query generation.
+assert isinstance(Pet.is_tail_wagging, ft3.Field)
+assert isinstance(Pet.type_, ft3.Field)
+
+assert dog.type_ == Pet.type_.default == 'dog'
+
+query = (
+    (
+        (Pet.type_ == 'dog')
+        & (Pet.name == 'Fido')
+        )
+    | Pet.name % ('fido', 0.75)
+    )
+query += 'name'
+assert dict(query) == {
+    'limit': None,
+    'or': [
+        {
+            'and': [
+                {
+                    'eq': 'dog',
+                    'field': 'type',
+                    'limit': None,
+                    'sorting': []
+                    },
+                {
+                    'eq': 'Fido',
+                    'field': 'name',
+                    'limit': None,
+                    'sorting': []
+                    }
+                ],
+            'limit': None,
+            'sorting': []
+            },
+        {
+            'field': 'name',
+            'like': 'fido',
+            'limit': None,
+            'sorting': [],
+            'threshold': 0.75
+            }
+        ],
+    'sorting': [
+        {
+            'direction': 'asc',
+            'field': 'name'
+            }
+        ]
+    }
+
+```
+
+### Local Logging
+```py
+import ft3
+
+
+class AgentFlea(ft3.Object):
+    """Still a nuisance."""
+
+    name: ft3.Field[str] = 'FLEA'
+    api_key: ft3.Field[str] = '9ac868264f004600bdff50b7f5b3e8ad'
+    aws_access_key_id: ft3.Field[str] = 'falsePositive'
+    sneaky: ft3.Field[str] = 'AKIARJFBAG3EGHFG2FPN'
+
+
+# Automatic log configuration, cleansing, and redaction.
+
+print(AgentFlea())
+# >>>
+# {
+#   "level": WARNING,
+#   "time": 2024-02-26 18:50:20.317 UTC,
+#   "log": ft3.core.log,
+#   "data":   {
+#     "message": "Calls to print() will be silenced by ft3."
+#   }
+# }
+# {
+#   "api_key": "[ REDACTED :: API KEY ]",
+#   "aws_access_key_id": "falsePositive",
+#   "name": "FLEA",
+#   "sneaky": "[ REDACTED :: AWS ACCESS KEY ID ]"
+# }
+
+print(AgentFlea())
+# >>>
+# {
+#   "api_key": "[ REDACTED :: API KEY ]",
+#   "aws_access_key_id": "falsePositive",
+#   "name": "FLEA",
+#   "sneaky": "[ REDACTED :: AWS ACCESS KEY ID ]"
+# }
+
+```
+
+### Deployed Logging
+
+```py
+import os
+os.environ['ENV'] = 'DEV'
+
+import ft3
+
+assert (
+    ft3.core.constants.PackageConstants.ENV
+    in {
+        'dev', 'develop',
+        'qa', 'test', 'testing',
+        'uat', 'stg', 'stage', 'staging',
+        'prod', 'production',
+        }
+    )
+
+
+class AgentFlea(ft3.Object):
+    """Still a nuisance."""
+
+    name: ft3.Field[str] = 'FLEA'
+    api_key: ft3.Field[str] = '9ac868264f004600bdff50b7f5b3e8ad'
+    aws_access_key_id: ft3.Field[str] = 'falsePositive'
+    sneaky: ft3.Field[str] = 'AKIARJFBAG3EGHFG2FPN'
+
+
+print(AgentFlea())
+# >>>
+# {
+#   "level": WARNING,
+#   "time": 2024-02-26 19:02:29.020 UTC,
+#   "log": ft3.core.log,
+#   "data":   {
+#     "message": "Call to print() silenced by ft3.",
+#     "printed": "{\n  \"api_key\": \"[ REDACTED :: API KEY ]\",\n  \"aws_access_key_id\": \"falsePositive\",\n  \"name\": \"FLEA\",\n  \"sneaky\": \"[ REDACTED :: AWS ACCESS KEY ID ]\"\n}"
+#   }
+# }
+
+print(AgentFlea())
+# >>>
+
+ft3.log.info(AgentFlea())
+# >>>
+# {
+#   "level": INFO,
+#   "time": 2024-02-26 19:13:21.726 UTC,
+#   "log": ft3.core.log,
+#   "data":   {
+#     "AgentFlea": {
+#       "api_key": "[ REDACTED :: API KEY ]",
+#       "aws_access_key_id": "falsePositive",
+#       "name": "FLEA",
+#       "sneaky": "[ REDACTED :: AWS ACCESS KEY ID ]"
+#     }
+#   }
+# }
+
+```
+
+## Planned Features
+
+* #### RESTful Framework / OpenAPI Support
+    * ft3 should support all aspects of an OpenAPI specification and
+    provide corresponding framework functionality for HTTP request
+    handling.
+* #### Template Packages
+    * ft3 should include a Pet shop style demo API and python package
+    as a template for developers to copy / paste from.
+* #### Database Parse & Sync
+    * ft3 should be able to generate a python package with fully enumerated
+    and optimized `Objects` (and a corresponding ft3 API package) when
+    supplied with access to a database for which at least one schema may be
+    inferred.
+        * CLI commands like `$ ft3-api-from-sql ${api_name} ${sql_conn_string} .`
+        should instantly output two ideally structured package repositories for a
+        RESTful python API and corresponding object management package.
+        * The package could use any supplied credentials to either query a database
+        directly or make requests to a deployed API. This means the same package
+        used to power the API can be distributed and pip installed across an
+        organization so business intelligence, data science, and other technical
+        team members can manipulate data for their needs, while leaning on
+        the package to optimize queries and stay informed around permission
+        boundaries and request limits.
+* #### Repo Generation
+    * ft3 should be expanded to optionally wrap any generated packages
+    in a repository pre-configured with essentials and CI that should:
+        * implement an ideal [trunk-based branch strategy](https://trunkbaseddevelopment.com/),
+        inline with current best practices for change management and
+        developer collaboration
+        * enforce python code style best practices through automated
+        [linting and formatting](https://docs.astral.sh/ruff)
+        * type-check python code and generate a report with [mypy](https://mypy.readthedocs.io/en/stable/index.html)
+        * run tests automatically, generate reports, and prevent commits that break tests
+        * automatically prevent commits that do not adhere to standardized commit
+        message [conventions](https://www.conventionalcommits.org/en/v1.0.0/)
+        * using those conventions, automatically [semantically version](https://python-semantic-release.readthedocs.io/en/stable/#getting-started)
+        each successful PR and automatically generate and update a
+        CHANGELOG.md file
+        * automatically generate and publish secure wiki documentation
+    * Generated repos may contain up to all of the following:
+        * CHANGELOG.md
+        * CODEOWNERS
+        * CONTRIBUTING.md
+        * .git
+            * .git/hooks/
+        * .github/workflows/
+            * Support planned for gitlab and bamboo.
+        * .gitignore
+        * LICENSE
+        * [.pre-commit-config.yaml](https://pre-commit.com/#intro)
+        * pyproject.toml
+        * README.md
+        * /src
+            * /package
+            * /tests
+
+## Acknowledgments
+
+* #### @sol.courtney
+    * Teaching me the difference between chicken-scratch, duct tape, and bubble
+    gum versus actual engineering, and why it matters.