Verified Commit d8230655 authored by Manuel Vazquez Acosta's avatar Manuel Vazquez Acosta
Browse files

Initial commit with a README and pledge.

parents
Pipeline #31580 failed with stages
in 34 seconds
;;;
;;; Directory Local Variables
;;; For more information see (info "(emacs) Directory Variables")
((python-mode . ((fill-column . 80))))
*.pyc
*.pyo
*.*~
*.*~*
.tox/
.cache/
.hypothesis/
.mypy_cache/
.pytest_cache/
__pycache__
build/
dist/
*.egg-info/
*#
#*
.coverage
.envrc
---
stages:
- pre-check
- build doc
- publish doc
- test
- check
- build
- publish
check code smells:
image: python:3.8
script:
- |
pip install tox
tox -e system-lint
stage: pre-check
allow_failure: true
only:
- main
- merge_requests
interruptible: true
tags:
- docker
.run_tox_tests: &run_tox_tests
image: python:$PYTHON-alpine
stage: test
script:
- pip install tox
- tox -e system-unit
interruptible: true
tags:
- docker
.run_tox_staticcheck: &run_tox_staticcheck
image: python:3.8
stage: pre-check
script:
- pip install tox
- tox -e 3.8-staticcheck
interruptible: true
tags:
- docker
.run_tox_doctest: &run_tox_doctest
image: python:3.8
stage: test
script:
- pip install tox
- tox -e system-doctest
interruptible: true
tags:
- docker
run tests:
<<: *run_tox_tests
only:
- main
- merge_requests
allow_failure: false
parallel:
matrix:
- PYTHON: ["3.8", "3.9", "3.10"]
run static checks:
<<: *run_tox_staticcheck
only:
- main
- merge_requests
run doctests:
<<: *run_tox_doctest
only:
- main
- merge_requests
run coverage tests:
image: python:3.8
stage: test
script:
- pip install tox
- tox -e system-coverage
allow_failure: true
only:
- main
- merge_requests
interruptible: true
tags:
- docker
check signature of tag:
image: alpine
stage: check
script:
- apk add git gnupg
- cat $GNUPG_KEY_FILE | gpg --import
- git verify-tag $CI_COMMIT_REF_NAME
only:
refs:
- tags
variables:
- $CI_COMMIT_TAG =~ /^\d+(\.\d+)*(|a\d+|b\d+|rc\d+)?(\.post\d+|\.dev\d+)?$/
build source distribution:
image: python:3.8
stage: build
script:
- apt-get update && apt-get install -y git
- rm -f dist/*
- python setup.py sdist
artifacts:
paths:
- dist/
only:
refs:
- tags
variables:
- $CI_COMMIT_TAG =~ /^\d+(\.\d+)*(|a\d+|b\d+|rc\d+)?(\.post\d+|\.dev\d+)?$/
build binary distribution:
image: python:3.8
stage: build
script:
- apt-get update && apt-get install -y git
- pip install wheel
- python setup.py bdist_wheel
artifacts:
paths:
- dist/
only:
refs:
- tags
variables:
- $CI_COMMIT_TAG =~ /^\d+(\.\d+)*(|a\d+|b\d+|rc\d+)?(\.post\d+|\.dev\d+)?$/
publish_pypi:
image: python:3.8
stage: publish
script:
- pip install twine
- twine upload -u "$PYPI_USERNAME" -p "$PYPI_PASSWORD" dist/*
only:
refs:
- tags
variables:
- $CI_COMMIT_TAG =~ /^\d+(\.\d+)*(|a\d+|b\d+|rc\d+)?(\.post\d+)?$/
dependencies:
- check signature of tag
- build source distribution
- build binary distribution
environment:
name: pypi
url: https://pypi.python.org/pypi/$CI_PROJECT_NAME
.build_doc: &build_documentation
image: python:3.9
script:
- |
apt-get update && apt-get install -y git
pip install -U sphinx sphinx-rtd-theme
pip install -e .
make -C docs/ html
mkdir -p public
cp -rf docs/build/html/* public/
interruptible: true
tags:
- docker
build documentation in MRs:
<<: *build_documentation
interruptible: true
stage: build
needs: []
artifacts:
paths:
- public
cache:
paths:
- docs/build/
key: $CI_JOB_NAME
only:
refs:
- merge_requests
changes:
- docs/**/*.rst
- xotl/**/*.py
build documentation:
<<: *build_documentation
stage: build
needs: []
artifacts:
paths:
- public
cache:
paths:
- docs/build/
key: $CI_JOB_NAME
only:
- main
- tags
.x-publish-doc-rdt: &with-publish-doc-rtd
image: alpine
variables:
GIT_STRATEGY: none
stage: publish
script:
- |
apk add openssh rsync
mkdir -p $HOME/.ssh
chmod 700 $HOME/.ssh
cp $RSA_KEY_FILE $HOME/.ssh/id_rsa
chmod 600 $HOME/.ssh/id_rsa
cp $SSH_CONFIG_FILE $HOME/.ssh/config
ssh docs.lahavane.com mkdir -p /data/$CI_PROJECT_NAME/.$CI_COMMIT_SHA
rsync -auvp -e ssh ./public/ docs.lahavane.com:/data/$CI_PROJECT_NAME/.$CI_COMMIT_SHA/
ssh docs.lahavane.com "cd /data/$CI_PROJECT_NAME; rm -r $CI_COMMIT_REF_NAME; ln -s .$CI_COMMIT_SHA $CI_COMMIT_REF_NAME"
ssh docs.lahavane.com "cd /data/$CI_PROJECT_NAME; ls -al | grep -oE '\.([0-9]|[a-z])*$' | sort | uniq -c | grep '1 ' | grep -oE '\.([0-9]|[a-z])*$' | xargs rm -rf"
environment:
name: docs.lahavane.com
url: http://docs.lahavane.com/$CI_PROJECT_NAME/$CI_COMMIT_REF_NAME
publish in our rtd in MRs:
<<: *with-publish-doc-rtd
interruptible: true
needs:
- build documentation in MRs
only:
refs:
- merge_requests
changes:
- docs/**/*.rst
- xotl/**/*.py
publish in our rtd:
<<: *with-publish-doc-rtd
needs:
- build documentation
only:
- main
- tags
pages:
<<: *build_documentation
stage: build
needs: []
artifacts:
paths:
- public
only:
- main
docs/source/history.rst
\ No newline at end of file
Copyright © 2021 Manuel Vázquez Acosta
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the “Software”), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
include *.py
include *.ini
include *.rst
recursive-include docs *.rst *.txt Makefile *.py
recursive-include xotl *.py *.rst *.pyi
prune .tox
prune docs/build
===================================
Organizing your Majestic Monolith
===================================
What is ``xotl.gravity`` (Gravity)?
===================================
Gravity is a framework that allows you to separate the different *concerns* of
single runtime-components of your `Majestic Monolith <mm_>`__ into separate
code-level structures (mainly classes) and allows to bind them together in
disciplined way.
Gravity is best friends with `static typing <mypy_>`__ and Python regular
inheritance. Gravity likes many other of its friends like Django_,
SQLAlchemy_, Pydantic_, FastAPI_ and many others; even though, they some of
them can't be in the same party most of the time.
Gravity is designed to be as easy as possible to party and integrate with some
chosen friend, but she is also very friendly to be introduced to new ones.
Every layer of her is `fully documented <Gravity_>`__.
Why does Gravity exist?
=======================
Otherwise we wouldn't exist at all! ;)
This is a long story which is best explained elsewhere. But I need to write
something about it anyways:
I worked with `Ruby on Rails`_ many years ago and I liked it; I also worked
with Odoo_ in the recent past for many years in a row and I get used to
splitting a single model in several classes; now I'm coming back to Django,
and I need more or less the same without complicating the DB layout or
disrupting the Universe with microclusters of services.
In its own way, Gravity is my attempt to unify all those years of experience
without tying myself to a single framework, many of which are suitable only
for a small part of the possible architectures allowed.
Do I need Gravity?
==================
If your site a micro-something or a web site to manage a TODO list, maybe
Gravity is not for you. You might just stick with Django, SQLAlchemy + Flask
or Pyramid or whatever you're comfortable with.
If, on the other hand, your project is becoming more complex and you need to
start organizing you code into different around concerns *of the same basic
model*, then you might benefit from Gravity to help you make all those thing
fall into place while retaining a clear source code separation and the
benefits of incremental static typing.
Best of luck!
.. _mm: https://m.signalvnoise.com/the-majestic-monolith/
.. _mypy: https://mypy.readthedocs.io/
.. _django: https://docs.djangoproject.com/
.. _SQLAlchemy: https://www.sqlalchemy.org/
.. _Pydantic: https://pydantic-docs.helpmanual.io/
.. _FastAPI: https://fastapi.tiangolo.com/
.. _Gravity: https://xotl-gravity.github.io/
.. _Odoo: https://github.com/odoo/odoo
.. _Ruby on Rails: https://rubyonrails.org/
# Minimal makefile for Sphinx documentation
#
# You can set these variables from the command line, and also
# from the environment for the first two.
SPHINXOPTS ?=
SPHINXBUILD ?= sphinx-build
SOURCEDIR = source
BUILDDIR = build
# Put it first so that "make" without argument is like "make help".
help:
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
.PHONY: help Makefile
# Catch-all target: route all unknown targets to Sphinx using the new
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
%: Makefile
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
@ECHO OFF
pushd %~dp0
REM Command file for Sphinx documentation
if "%SPHINXBUILD%" == "" (
set SPHINXBUILD=sphinx-build
)
set SOURCEDIR=source
set BUILDDIR=build
if "%1" == "" goto help
%SPHINXBUILD% >NUL 2>NUL
if errorlevel 9009 (
echo.
echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
echo.installed, then set the SPHINXBUILD environment variable to point
echo.to the full path of the 'sphinx-build' executable. Alternatively you
echo.may add the Sphinx directory to PATH.
echo.
echo.If you don't have Sphinx installed, grab it from
echo.https://www.sphinx-doc.org/
exit /b 1
)
%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
goto end
:help
%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
:end
popd
# Configuration file for the Sphinx documentation builder.
#
# This file only contains a selection of the most common options. For a full
# list see the documentation:
# https://www.sphinx-doc.org/en/master/usage/configuration.html
# -- Path setup --------------------------------------------------------------
# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
#
# import os
# import sys
# sys.path.insert(0, os.path.abspath('.'))
# -- Project information -----------------------------------------------------
from datetime import datetime
project = "xotl.gravity"
copyright = "{}, Manuel Vázquez Acosta"
copyright = copyright.format(datetime.now().year)
author = "Manuel Vázquez Acosta"
import pkg_resources
dist = pkg_resources.get_distribution("xotl.gravity")
version = dist.version
release = version
# -- General configuration ---------------------------------------------------
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = [
"sphinx.ext.autodoc",
"sphinx.ext.doctest",
"sphinx.ext.intersphinx",
"sphinx.ext.viewcode",
]
# Add any paths that contain templates here, relative to this directory.
templates_path = ["_templates"]
# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
# This pattern also affects html_static_path and html_extra_path.
exclude_patterns = []
# -- Options for HTML output -------------------------------------------------
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
#
try:
import sphinx_rtd_theme as theme
html_theme = "sphinx_rtd_theme"
html_theme_path = [theme.get_html_theme_path()]
except ImportError:
html_theme = "pyramid"
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = ["_static"]
intersphinx_mapping = {"https://docs.python.org/": None}
===============
Release notes
===============
Pre-stable series of releases 0.x
=================================
The whole series of releases starting from 0.1.0 must be considered unstable.
I will try to keep the API as stable as possible since the first release but I
won't commit to a deprecation calendar and any other lengthy process to manage
the API.
At this point is better to pin Gravity's version always using ``~=0.x.y`` (so
that you don't get ``0.x+1``).
===================================
Organizing your Majestic Monolith
===================================
What is ``xotl.gravity`` (Gravity)?
===================================
Gravity is a framework that allows you to separate the different *concerns* of
single runtime-components of your `Majestic Monolith <mm_>`__ into separate
code-level structures (mainly classes) and allows to bind them together in
disciplined way.
Gravity is best friends with `static typing <mypy_>`__ and Python regular
inheritance. Gravity likes many other of its friends like Django_,
SQLAlchemy_, Pydantic_, FastAPI_ and many others; even though, they some of
them can't be in the same party most of the time.
Gravity is designed to be as easy as possible to party and integrate with some
chosen friend, but she is also very friendly to be introduced to new ones.
Every layer of her is `fully documented <Gravity_>`__.
Why does Gravity exist?
=======================
Otherwise we wouldn't exist at all! ;)
This is a long story which is best explained elsewhere. But I need to write
something about it anyways:
I worked with `Ruby on Rails`_ many years ago and I liked it; I also worked
with Odoo_ in the recent past for many years in a row and I get used to
splitting a single model in several classes; now I'm coming back to Django,
and I need more or less the same without complicating the DB layout or
disrupting the Universe with microclusters of services.
In its own way, Gravity is my attempt to unify all those years of experience
without tying myself to be kept into a single framework, many of which are
suitable only for a small part of the possible architectures.
Do I need Gravity?
==================
If your site a micro-something or a web site to manage a TODO list, maybe
Gravity is not for you. You might just stick with Django, SQLAlchemy + Flask
or Pyramid or whatever you're comfortable with.
If, on the other hand, your project is becoming more complex and you need to
start organizing you code into different around concerns *of the same basic
model*, then you might benefit from Gravity to help you make all those thing
fall into place while retaining a clear source code separation and the
benefits of incremental static typing.
Best of luck!
Documentation
=============
.. toctree::
:glob:
:maxdepth: 2
:caption: Contents:
narrative/*
api/*
history
Indices and tables
------------------
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`
.. _mm: https://m.signalvnoise.com/the-majestic-monolith/
.. _mypy: https://mypy.readthedocs.io/
.. _django: https://docs.djangoproject.com/
.. _SQLAlchemy: https://www.sqlalchemy.org/
.. _Pydantic: https://pydantic-docs.helpmanual.io/
.. _FastAPI: https://fastapi.tiangolo.com/
.. _Gravity: https://xotl-gravity.github.io/
.. _Odoo: https://github.com/odoo/odoo
.. _Ruby on Rails: https://rubyonrails.org/
[mypy]
namespace_packages = True
warn_unused_ignores = True
strict_equality = True
show_error_context = True
show_error_codes = True
[build-system]
requires = ["setuptools", "wheel"]
build-backend = "setuptools.build_meta:__legacy__"
[tool.black]
line-length = 80
target-version = ['py38']
[metadata]