From fe24d79f37027acda6487877756d676a186b2fcc Mon Sep 17 00:00:00 2001 From: Jayaram Kancherla Date: Thu, 25 Jan 2024 19:43:10 -0800 Subject: [PATCH] Initial commit --- .coveragerc | 28 +++ .gitignore | 54 +++++ .readthedocs.yml | 27 +++ AUTHORS.md | 3 + CHANGELOG.md | 7 + CONTRIBUTING.md | 371 +++++++++++++++++++++++++++++++++++ LICENSE.txt | 21 ++ README.md | 27 +++ docs/Makefile | 29 +++ docs/_static/.gitignore | 1 + docs/authors.md | 4 + docs/changelog.md | 4 + docs/conf.py | 304 ++++++++++++++++++++++++++++ docs/contributing.md | 4 + docs/index.md | 39 ++++ docs/license.md | 5 + docs/readme.md | 4 + docs/requirements.txt | 6 + pyproject.toml | 9 + setup.cfg | 125 ++++++++++++ setup.py | 21 ++ src/dolomite_mae/__init__.py | 16 ++ src/dolomite_mae/skeleton.py | 149 ++++++++++++++ tests/conftest.py | 10 + tests/test_skeleton.py | 25 +++ tox.ini | 93 +++++++++ 26 files changed, 1386 insertions(+) create mode 100644 .coveragerc create mode 100644 .gitignore create mode 100644 .readthedocs.yml create mode 100644 AUTHORS.md create mode 100644 CHANGELOG.md create mode 100644 CONTRIBUTING.md create mode 100644 LICENSE.txt create mode 100644 README.md create mode 100644 docs/Makefile create mode 100644 docs/_static/.gitignore create mode 100644 docs/authors.md create mode 100644 docs/changelog.md create mode 100644 docs/conf.py create mode 100644 docs/contributing.md create mode 100644 docs/index.md create mode 100644 docs/license.md create mode 100644 docs/readme.md create mode 100644 docs/requirements.txt create mode 100644 pyproject.toml create mode 100644 setup.cfg create mode 100644 setup.py create mode 100644 src/dolomite_mae/__init__.py create mode 100644 src/dolomite_mae/skeleton.py create mode 100644 tests/conftest.py create mode 100644 tests/test_skeleton.py create mode 100644 tox.ini diff --git a/.coveragerc b/.coveragerc new file mode 100644 index 0000000..56e5bfd --- /dev/null +++ b/.coveragerc @@ -0,0 +1,28 @@ +# .coveragerc to control coverage.py +[run] +branch = True +source = dolomite_mae +# omit = bad_file.py + +[paths] +source = + src/ + */site-packages/ + +[report] +# Regexes for lines to exclude from consideration +exclude_lines = + # Have to re-enable the standard pragma + pragma: no cover + + # Don't complain about missing debug-only code: + def __repr__ + if self\.debug + + # Don't complain if tests don't hit defensive assertion code: + raise AssertionError + raise NotImplementedError + + # Don't complain if non-runnable code isn't run: + if 0: + if __name__ == .__main__.: diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..e9e1e9b --- /dev/null +++ b/.gitignore @@ -0,0 +1,54 @@ +# Temporary and binary files +*~ +*.py[cod] +*.so +*.cfg +!.isort.cfg +!setup.cfg +*.orig +*.log +*.pot +__pycache__/* +.cache/* +.*.swp +*/.ipynb_checkpoints/* +.DS_Store + +# Project files +.ropeproject +.project +.pydevproject +.settings +.idea +.vscode +tags + +# Package files +*.egg +*.eggs/ +.installed.cfg +*.egg-info + +# Unittest and coverage +htmlcov/* +.coverage +.coverage.* +.tox +junit*.xml +coverage.xml +.pytest_cache/ + +# Build and docs folder/files +build/* +dist/* +sdist/* +docs/api/* +docs/_rst/* +docs/_build/* +cover/* +MANIFEST + +# Per-project virtualenvs +.venv*/ +.conda*/ +.python-version diff --git a/.readthedocs.yml b/.readthedocs.yml new file mode 100644 index 0000000..a2bcab3 --- /dev/null +++ b/.readthedocs.yml @@ -0,0 +1,27 @@ +# Read the Docs configuration file +# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details + +# Required +version: 2 + +# Build documentation in the docs/ directory with Sphinx +sphinx: + configuration: docs/conf.py + +# Build documentation with MkDocs +#mkdocs: +# configuration: mkdocs.yml + +# Optionally build your docs in additional formats such as PDF +formats: + - pdf + +build: + os: ubuntu-22.04 + tools: + python: "3.11" + +python: + install: + - requirements: docs/requirements.txt + - {path: ., method: pip} diff --git a/AUTHORS.md b/AUTHORS.md new file mode 100644 index 0000000..f21a024 --- /dev/null +++ b/AUTHORS.md @@ -0,0 +1,3 @@ +# Contributors + +* Jayaram Kancherla [jayaram.kancherla@gmail.com](mailto:jayaram.kancherla@gmail.com) diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..205cc5e --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,7 @@ +# Changelog + +## Version 0.1 (development) + +- Feature A added +- FIX: nasty bug #1729 fixed +- add your changes here! diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..39dd201 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,371 @@ +```{todo} THIS IS SUPPOSED TO BE AN EXAMPLE. MODIFY IT ACCORDING TO YOUR NEEDS! + + The document assumes you are using a source repository service that promotes a + contribution model similar to [GitHub's fork and pull request workflow]. + While this is true for the majority of services (like GitHub, GitLab, + BitBucket), it might not be the case for private repositories (e.g., when + using Gerrit). + + Also notice that the code examples might refer to GitHub URLs or the text + might use GitHub specific terminology (e.g., *Pull Request* instead of *Merge + Request*). + + Please make sure to check the document having these assumptions in mind + and update things accordingly. +``` + +```{todo} Provide the correct links/replacements at the bottom of the document. +``` + +```{todo} You might want to have a look on [PyScaffold's contributor's guide], + + especially if your project is open source. The text should be very similar to + this template, but there are a few extra contents that you might decide to + also include, like mentioning labels of your issue tracker or automated + releases. +``` + +# Contributing + +Welcome to `dolomite-mae` contributor's guide. + +This document focuses on getting any potential contributor familiarized with +the development processes, but [other kinds of contributions] are also appreciated. + +If you are new to using [git] or have never collaborated in a project previously, +please have a look at [contribution-guide.org]. Other resources are also +listed in the excellent [guide created by FreeCodeCamp] [^contrib1]. + +Please notice, all users and contributors are expected to be **open, +considerate, reasonable, and respectful**. When in doubt, +[Python Software Foundation's Code of Conduct] is a good reference in terms of +behavior guidelines. + +## Issue Reports + +If you experience bugs or general issues with `dolomite-mae`, please have a look +on the [issue tracker]. +If you don't see anything useful there, please feel free to fire an issue report. + +:::{tip} +Please don't forget to include the closed issues in your search. +Sometimes a solution was already reported, and the problem is considered +**solved**. +::: + +New issue reports should include information about your programming environment +(e.g., operating system, Python version) and steps to reproduce the problem. +Please try also to simplify the reproduction steps to a very minimal example +that still illustrates the problem you are facing. By removing other factors, +you help us to identify the root cause of the issue. + +## Documentation Improvements + +You can help improve `dolomite-mae` docs by making them more readable and coherent, or +by adding missing information and correcting mistakes. + +`dolomite-mae` documentation uses [Sphinx] as its main documentation compiler. +This means that the docs are kept in the same repository as the project code, and +that any documentation update is done in the same way was a code contribution. + +```{todo} Don't forget to mention which markup language you are using. + + e.g., [reStructuredText] or [CommonMark] with [MyST] extensions. +``` + +```{todo} If your project is hosted on GitHub, you can also mention the following tip: + + :::{tip} + Please notice that the [GitHub web interface] provides a quick way of + propose changes in `dolomite-mae`'s files. While this mechanism can + be tricky for normal code contributions, it works perfectly fine for + contributing to the docs, and can be quite handy. + + If you are interested in trying this method out, please navigate to + the `docs` folder in the source [repository], find which file you + would like to propose changes and click in the little pencil icon at the + top, to open [GitHub's code editor]. Once you finish editing the file, + please write a message in the form at the bottom of the page describing + which changes have you made and what are the motivations behind them and + submit your proposal. + ::: +``` + +When working on documentation changes in your local machine, you can +compile them using [tox] : + +``` +tox -e docs +``` + +and use Python's built-in web server for a preview in your web browser +(`http://localhost:8000`): + +``` +python3 -m http.server --directory 'docs/_build/html' +``` + +## Code Contributions + +```{todo} Please include a reference or explanation about the internals of the project. + + An architecture description, design principles or at least a summary of the + main concepts will make it easy for potential contributors to get started + quickly. +``` + +### Submit an issue + +Before you work on any non-trivial code contribution it's best to first create +a report in the [issue tracker] to start a discussion on the subject. +This often provides additional considerations and avoids unnecessary work. + +### Create an environment + +Before you start coding, we recommend creating an isolated [virtual environment] +to avoid any problems with your installed Python packages. +This can easily be done via either [virtualenv]: + +``` +virtualenv +source /bin/activate +``` + +or [Miniconda]: + +``` +conda create -n dolomite-mae python=3 six virtualenv pytest pytest-cov +conda activate dolomite-mae +``` + +### Clone the repository + +1. Create an user account on GitHub if you do not already have one. + +2. Fork the project [repository]: click on the *Fork* button near the top of the + page. This creates a copy of the code under your account on GitHub. + +3. Clone this copy to your local disk: + + ``` + git clone git@github.com:YourLogin/dolomite-mae.git + cd dolomite-mae + ``` + +4. You should run: + + ``` + pip install -U pip setuptools -e . + ``` + + to be able to import the package under development in the Python REPL. + + ```{todo} if you are not using pre-commit, please remove the following item: + ``` + +5. Install [pre-commit]: + + ``` + pip install pre-commit + pre-commit install + ``` + + `dolomite-mae` comes with a lot of hooks configured to automatically help the + developer to check the code being written. + +### Implement your changes + +1. Create a branch to hold your changes: + + ``` + git checkout -b my-feature + ``` + + and start making changes. Never work on the main branch! + +2. Start your work on this branch. Don't forget to add [docstrings] to new + functions, modules and classes, especially if they are part of public APIs. + +3. Add yourself to the list of contributors in `AUTHORS.rst`. + +4. When you’re done editing, do: + + ``` + git add + git commit + ``` + + to record your changes in [git]. + + ```{todo} if you are not using pre-commit, please remove the following item: + ``` + + Please make sure to see the validation messages from [pre-commit] and fix + any eventual issues. + This should automatically use [flake8]/[black] to check/fix the code style + in a way that is compatible with the project. + + :::{important} + Don't forget to add unit tests and documentation in case your + contribution adds an additional feature and is not just a bugfix. + + Moreover, writing a [descriptive commit message] is highly recommended. + In case of doubt, you can check the commit history with: + + ``` + git log --graph --decorate --pretty=oneline --abbrev-commit --all + ``` + + to look for recurring communication patterns. + ::: + +5. Please check that your changes don't break any unit tests with: + + ``` + tox + ``` + + (after having installed [tox] with `pip install tox` or `pipx`). + + You can also use [tox] to run several other pre-configured tasks in the + repository. Try `tox -av` to see a list of the available checks. + +### Submit your contribution + +1. If everything works fine, push your local branch to the remote server with: + + ``` + git push -u origin my-feature + ``` + +2. Go to the web page of your fork and click "Create pull request" + to send your changes for review. + + ```{todo} if you are using GitHub, you can uncomment the following paragraph + + Find more detailed information in [creating a PR]. You might also want to open + the PR as a draft first and mark it as ready for review after the feedbacks + from the continuous integration (CI) system or any required fixes. + + ``` + +### Troubleshooting + +The following tips can be used when facing problems to build or test the +package: + +1. Make sure to fetch all the tags from the upstream [repository]. + The command `git describe --abbrev=0 --tags` should return the version you + are expecting. If you are trying to run CI scripts in a fork repository, + make sure to push all the tags. + You can also try to remove all the egg files or the complete egg folder, i.e., + `.eggs`, as well as the `*.egg-info` folders in the `src` folder or + potentially in the root of your project. + +2. Sometimes [tox] misses out when new dependencies are added, especially to + `setup.cfg` and `docs/requirements.txt`. If you find any problems with + missing dependencies when running a command with [tox], try to recreate the + `tox` environment using the `-r` flag. For example, instead of: + + ``` + tox -e docs + ``` + + Try running: + + ``` + tox -r -e docs + ``` + +3. Make sure to have a reliable [tox] installation that uses the correct + Python version (e.g., 3.7+). When in doubt you can run: + + ``` + tox --version + # OR + which tox + ``` + + If you have trouble and are seeing weird errors upon running [tox], you can + also try to create a dedicated [virtual environment] with a [tox] binary + freshly installed. For example: + + ``` + virtualenv .venv + source .venv/bin/activate + .venv/bin/pip install tox + .venv/bin/tox -e all + ``` + +4. [Pytest can drop you] in an interactive session in the case an error occurs. + In order to do that you need to pass a `--pdb` option (for example by + running `tox -- -k --pdb`). + You can also setup breakpoints manually instead of using the `--pdb` option. + +## Maintainer tasks + +### Releases + +```{todo} This section assumes you are using PyPI to publicly release your package. + + If instead you are using a different/private package index, please update + the instructions accordingly. +``` + +If you are part of the group of maintainers and have correct user permissions +on [PyPI], the following steps can be used to release a new version for +`dolomite-mae`: + +1. Make sure all unit tests are successful. +2. Tag the current commit on the main branch with a release tag, e.g., `v1.2.3`. +3. Push the new tag to the upstream [repository], + e.g., `git push upstream v1.2.3` +4. Clean up the `dist` and `build` folders with `tox -e clean` + (or `rm -rf dist build`) + to avoid confusion with old builds and Sphinx docs. +5. Run `tox -e build` and check that the files in `dist` have + the correct version (no `.dirty` or [git] hash) according to the [git] tag. + Also check the sizes of the distributions, if they are too big (e.g., > + 500KB), unwanted clutter may have been accidentally included. +6. Run `tox -e publish -- --repository pypi` and check that everything was + uploaded to [PyPI] correctly. + +[^contrib1]: Even though, these resources focus on open source projects and + communities, the general ideas behind collaborating with other developers + to collectively create software are general and can be applied to all sorts + of environments, including private companies and proprietary code bases. + + +[black]: https://pypi.org/project/black/ +[commonmark]: https://commonmark.org/ +[contribution-guide.org]: http://www.contribution-guide.org/ +[creating a pr]: https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request +[descriptive commit message]: https://chris.beams.io/posts/git-commit +[docstrings]: https://www.sphinx-doc.org/en/master/usage/extensions/napoleon.html +[first-contributions tutorial]: https://github.com/firstcontributions/first-contributions +[flake8]: https://flake8.pycqa.org/en/stable/ +[git]: https://git-scm.com +[github web interface]: https://docs.github.com/en/github/managing-files-in-a-repository/managing-files-on-github/editing-files-in-your-repository +[github's code editor]: https://docs.github.com/en/github/managing-files-in-a-repository/managing-files-on-github/editing-files-in-your-repository +[github's fork and pull request workflow]: https://guides.github.com/activities/forking/ +[guide created by freecodecamp]: https://github.com/freecodecamp/how-to-contribute-to-open-source +[miniconda]: https://docs.conda.io/en/latest/miniconda.html +[myst]: https://myst-parser.readthedocs.io/en/latest/syntax/syntax.html +[other kinds of contributions]: https://opensource.guide/how-to-contribute +[pre-commit]: https://pre-commit.com/ +[pypi]: https://pypi.org/ +[pyscaffold's contributor's guide]: https://pyscaffold.org/en/stable/contributing.html +[pytest can drop you]: https://docs.pytest.org/en/stable/usage.html#dropping-to-pdb-python-debugger-at-the-start-of-a-test +[python software foundation's code of conduct]: https://www.python.org/psf/conduct/ +[restructuredtext]: https://www.sphinx-doc.org/en/master/usage/restructuredtext/ +[sphinx]: https://www.sphinx-doc.org/en/master/ +[tox]: https://tox.readthedocs.io/en/stable/ +[virtual environment]: https://realpython.com/python-virtual-environments-a-primer/ +[virtualenv]: https://virtualenv.pypa.io/en/stable/ + + +```{todo} Please review and change the following definitions: +``` + +[repository]: https://github.com//dolomite-mae +[issue tracker]: https://github.com//dolomite-mae/issues diff --git a/LICENSE.txt b/LICENSE.txt new file mode 100644 index 0000000..a378847 --- /dev/null +++ b/LICENSE.txt @@ -0,0 +1,21 @@ +The MIT License (MIT) + +Copyright (c) 2024 Jayaram Kancherla + +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. diff --git a/README.md b/README.md new file mode 100644 index 0000000..05f5469 --- /dev/null +++ b/README.md @@ -0,0 +1,27 @@ + + +[![Project generated with PyScaffold](https://img.shields.io/badge/-PyScaffold-005CA0?logo=pyscaffold)](https://pyscaffold.org/) + +# dolomite-mae + +> Add a short description here! + +A longer description of your project goes here... + + + + +## Note + +This project has been set up using PyScaffold 4.5. For details and usage +information on PyScaffold see https://pyscaffold.org/. diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..31655dd --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,29 @@ +# 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 = . +BUILDDIR = _build +AUTODOCDIR = api + +# User-friendly check for sphinx-build +ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $?), 1) +$(error "The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from https://sphinx-doc.org/") +endif + +.PHONY: help clean Makefile + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +clean: + rm -rf $(BUILDDIR)/* $(AUTODOCDIR) + +# 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) diff --git a/docs/_static/.gitignore b/docs/_static/.gitignore new file mode 100644 index 0000000..3c96363 --- /dev/null +++ b/docs/_static/.gitignore @@ -0,0 +1 @@ +# Empty directory diff --git a/docs/authors.md b/docs/authors.md new file mode 100644 index 0000000..ced47d0 --- /dev/null +++ b/docs/authors.md @@ -0,0 +1,4 @@ +```{include} ../AUTHORS.md +:relative-docs: docs/ +:relative-images: +``` diff --git a/docs/changelog.md b/docs/changelog.md new file mode 100644 index 0000000..6e2f0fb --- /dev/null +++ b/docs/changelog.md @@ -0,0 +1,4 @@ +```{include} ../CHANGELOG.md +:relative-docs: docs/ +:relative-images: +``` diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 0000000..a6c0f39 --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,304 @@ +# This file is execfile()d with the current directory set to its containing dir. +# +# 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 +# +# All configuration values have a default; values that are commented out +# serve to show the default. + +import os +import sys +import shutil + +# -- Path setup -------------------------------------------------------------- + +__location__ = os.path.dirname(__file__) + +# 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. +sys.path.insert(0, os.path.join(__location__, "../src")) + +# -- Run sphinx-apidoc ------------------------------------------------------- +# This hack is necessary since RTD does not issue `sphinx-apidoc` before running +# `sphinx-build -b html . _build/html`. See Issue: +# https://github.com/readthedocs/readthedocs.org/issues/1139 +# DON'T FORGET: Check the box "Install your project inside a virtualenv using +# setup.py install" in the RTD Advanced Settings. +# Additionally it helps us to avoid running apidoc manually + +try: # for Sphinx >= 1.7 + from sphinx.ext import apidoc +except ImportError: + from sphinx import apidoc + +output_dir = os.path.join(__location__, "api") +module_dir = os.path.join(__location__, "../src/dolomite_mae") +try: + shutil.rmtree(output_dir) +except FileNotFoundError: + pass + +try: + import sphinx + + cmd_line = f"sphinx-apidoc --implicit-namespaces -f -o {output_dir} {module_dir}" + + args = cmd_line.split(" ") + if tuple(sphinx.__version__.split(".")) >= ("1", "7"): + # This is a rudimentary parse_version to avoid external dependencies + args = args[1:] + + apidoc.main(args) +except Exception as e: + print("Running `sphinx-apidoc` failed!\n{}".format(e)) + +# -- General configuration --------------------------------------------------- + +# If your documentation needs a minimal Sphinx version, state it here. +# needs_sphinx = '1.0' + +# 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.intersphinx", + "sphinx.ext.todo", + "sphinx.ext.autosummary", + "sphinx.ext.viewcode", + "sphinx.ext.coverage", + "sphinx.ext.doctest", + "sphinx.ext.ifconfig", + "sphinx.ext.mathjax", + "sphinx.ext.napoleon", +] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ["_templates"] + + +# Enable markdown +extensions.append("myst_parser") + +# Configure MyST-Parser +myst_enable_extensions = [ + "amsmath", + "colon_fence", + "deflist", + "dollarmath", + "html_image", + "linkify", + "replacements", + "smartquotes", + "substitution", + "tasklist", +] + +# The suffix of source filenames. +source_suffix = [".rst", ".md"] + +# The encoding of source files. +# source_encoding = 'utf-8-sig' + +# The master toctree document. +master_doc = "index" + +# General information about the project. +project = "dolomite-mae" +copyright = "2024, Jayaram Kancherla" + +# The version info for the project you're documenting, acts as replacement for +# |version| and |release|, also used in various other places throughout the +# built documents. +# +# version: The short X.Y version. +# release: The full version, including alpha/beta/rc tags. +# If you don’t need the separation provided between version and release, +# just set them both to the same value. +try: + from dolomite_mae import __version__ as version +except ImportError: + version = "" + +if not version or version.lower() == "unknown": + version = os.getenv("READTHEDOCS_VERSION", "unknown") # automatically set by RTD + +release = version + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +# language = None + +# There are two options for replacing |today|: either, you set today to some +# non-false value, then it is used: +# today = '' +# Else, today_fmt is used as the format for a strftime call. +# today_fmt = '%B %d, %Y' + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +exclude_patterns = ["_build", "Thumbs.db", ".DS_Store", ".venv"] + +# The reST default role (used for this markup: `text`) to use for all documents. +# default_role = None + +# If true, '()' will be appended to :func: etc. cross-reference text. +# add_function_parentheses = True + +# If true, the current module name will be prepended to all description +# unit titles (such as .. function::). +# add_module_names = True + +# If true, sectionauthor and moduleauthor directives will be shown in the +# output. They are ignored by default. +# show_authors = False + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = "sphinx" + +# A list of ignored prefixes for module index sorting. +# modindex_common_prefix = [] + +# If true, keep warnings as "system message" paragraphs in the built documents. +# keep_warnings = False + +# If this is True, todo emits a warning for each TODO entries. The default is False. +todo_emit_warnings = True + + +# -- Options for HTML output ------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +html_theme = "alabaster" + +# Theme options are theme-specific and customize the look and feel of a theme +# further. For a list of options available for each theme, see the +# documentation. +html_theme_options = { + "sidebar_width": "300px", + "page_width": "1200px" +} + +# Add any paths that contain custom themes here, relative to this directory. +# html_theme_path = [] + +# The name for this set of Sphinx documents. If None, it defaults to +# " v documentation". +# html_title = None + +# A shorter title for the navigation bar. Default is the same as html_title. +# html_short_title = None + +# The name of an image file (relative to this directory) to place at the top +# of the sidebar. +# html_logo = "" + +# The name of an image file (within the static path) to use as favicon of the +# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 +# pixels large. +# html_favicon = None + +# 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"] + +# If not '', a 'Last updated on:' timestamp is inserted at every page bottom, +# using the given strftime format. +# html_last_updated_fmt = '%b %d, %Y' + +# If true, SmartyPants will be used to convert quotes and dashes to +# typographically correct entities. +# html_use_smartypants = True + +# Custom sidebar templates, maps document names to template names. +# html_sidebars = {} + +# Additional templates that should be rendered to pages, maps page names to +# template names. +# html_additional_pages = {} + +# If false, no module index is generated. +# html_domain_indices = True + +# If false, no index is generated. +# html_use_index = True + +# If true, the index is split into individual pages for each letter. +# html_split_index = False + +# If true, links to the reST sources are added to the pages. +# html_show_sourcelink = True + +# If true, "Created using Sphinx" is shown in the HTML footer. Default is True. +# html_show_sphinx = True + +# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. +# html_show_copyright = True + +# If true, an OpenSearch description file will be output, and all pages will +# contain a tag referring to it. The value of this option must be the +# base URL from which the finished HTML is served. +# html_use_opensearch = '' + +# This is the file name suffix for HTML files (e.g. ".xhtml"). +# html_file_suffix = None + +# Output file base name for HTML help builder. +htmlhelp_basename = "dolomite-mae-doc" + + +# -- Options for LaTeX output ------------------------------------------------ + +latex_elements = { + # The paper size ("letterpaper" or "a4paper"). + # "papersize": "letterpaper", + # The font size ("10pt", "11pt" or "12pt"). + # "pointsize": "10pt", + # Additional stuff for the LaTeX preamble. + # "preamble": "", +} + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, author, documentclass [howto/manual]). +latex_documents = [ + ("index", "user_guide.tex", "dolomite-mae Documentation", "Jayaram Kancherla", "manual") +] + +# The name of an image file (relative to this directory) to place at the top of +# the title page. +# latex_logo = "" + +# For "manual" documents, if this is true, then toplevel headings are parts, +# not chapters. +# latex_use_parts = False + +# If true, show page references after internal links. +# latex_show_pagerefs = False + +# If true, show URL addresses after external links. +# latex_show_urls = False + +# Documents to append as an appendix to all manuals. +# latex_appendices = [] + +# If false, no module index is generated. +# latex_domain_indices = True + +# -- External mapping -------------------------------------------------------- +python_version = ".".join(map(str, sys.version_info[0:2])) +intersphinx_mapping = { + "sphinx": ("https://www.sphinx-doc.org/en/master", None), + "python": ("https://docs.python.org/" + python_version, None), + "matplotlib": ("https://matplotlib.org", None), + "numpy": ("https://numpy.org/doc/stable", None), + "sklearn": ("https://scikit-learn.org/stable", None), + "pandas": ("https://pandas.pydata.org/pandas-docs/stable", None), + "scipy": ("https://docs.scipy.org/doc/scipy/reference", None), + "setuptools": ("https://setuptools.pypa.io/en/stable/", None), + "pyscaffold": ("https://pyscaffold.org/en/stable", None), +} + +print(f"loading configurations for {project} {version} ...", file=sys.stderr) \ No newline at end of file diff --git a/docs/contributing.md b/docs/contributing.md new file mode 100644 index 0000000..fc1b213 --- /dev/null +++ b/docs/contributing.md @@ -0,0 +1,4 @@ +```{include} ../CONTRIBUTING.md +:relative-docs: docs/ +:relative-images: +``` diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..056756a --- /dev/null +++ b/docs/index.md @@ -0,0 +1,39 @@ +# dolomite-mae + +Add a short description here! + + +## Note + +> This is the main page of your project's [Sphinx] documentation. It is +> formatted in [Markdown]. Add additional pages by creating md-files in +> `docs` or rst-files (formatted in [reStructuredText]) and adding links to +> them in the `Contents` section below. +> +> Please check [Sphinx] and [MyST] for more information +> about how to document your project and how to configure your preferences. + + +## Contents + +```{toctree} +:maxdepth: 2 + +Overview +Contributions & Help +License +Authors +Changelog +Module Reference +``` + +## Indices and tables + +* {ref}`genindex` +* {ref}`modindex` +* {ref}`search` + +[Sphinx]: http://www.sphinx-doc.org/ +[Markdown]: https://daringfireball.net/projects/markdown/ +[reStructuredText]: http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html +[MyST]: https://myst-parser.readthedocs.io/en/latest/ diff --git a/docs/license.md b/docs/license.md new file mode 100644 index 0000000..b231201 --- /dev/null +++ b/docs/license.md @@ -0,0 +1,5 @@ +# License + +```{literalinclude} ../LICENSE.txt +:language: text +``` diff --git a/docs/readme.md b/docs/readme.md new file mode 100644 index 0000000..2cb706b --- /dev/null +++ b/docs/readme.md @@ -0,0 +1,4 @@ +```{include} ../README.md +:relative-docs: docs/ +:relative-images: +``` diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 0000000..0990c2a --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1,6 @@ +# Requirements file for ReadTheDocs, check .readthedocs.yml. +# To build the module reference correctly, make sure every external package +# under `install_requires` in `setup.cfg` is also listed here! +# sphinx_rtd_theme +myst-parser[linkify] +sphinx>=3.2.1 diff --git a/pyproject.toml b/pyproject.toml new file mode 100644 index 0000000..89a5bed --- /dev/null +++ b/pyproject.toml @@ -0,0 +1,9 @@ +[build-system] +# AVOID CHANGING REQUIRES: IT WILL BE UPDATED BY PYSCAFFOLD! +requires = ["setuptools>=46.1.0", "setuptools_scm[toml]>=5"] +build-backend = "setuptools.build_meta" + +[tool.setuptools_scm] +# For smarter version schemes and other configuration options, +# check out https://github.com/pypa/setuptools_scm +version_scheme = "no-guess-dev" diff --git a/setup.cfg b/setup.cfg new file mode 100644 index 0000000..b60ac02 --- /dev/null +++ b/setup.cfg @@ -0,0 +1,125 @@ +# This file is used to configure your project. +# Read more about the various options under: +# https://setuptools.pypa.io/en/latest/userguide/declarative_config.html +# https://setuptools.pypa.io/en/latest/references/keywords.html + +[metadata] +name = dolomite-mae +description = Add a short description here! +author = Jayaram Kancherla +author_email = jayaram.kancherla@gmail.com +license = MIT +license_files = LICENSE.txt +long_description = file: README.md +long_description_content_type = text/markdown; charset=UTF-8; variant=GFM +url = https://github.com/pyscaffold/pyscaffold/ +# Add here related links, for example: +project_urls = + Documentation = https://pyscaffold.org/ +# Source = https://github.com/pyscaffold/pyscaffold/ +# Changelog = https://pyscaffold.org/en/latest/changelog.html +# Tracker = https://github.com/pyscaffold/pyscaffold/issues +# Conda-Forge = https://anaconda.org/conda-forge/pyscaffold +# Download = https://pypi.org/project/PyScaffold/#files +# Twitter = https://twitter.com/PyScaffold + +# Change if running only on Windows, Mac or Linux (comma-separated) +platforms = any + +# Add here all kinds of additional classifiers as defined under +# https://pypi.org/classifiers/ +classifiers = + Development Status :: 4 - Beta + Programming Language :: Python + + +[options] +zip_safe = False +packages = find_namespace: +include_package_data = True +package_dir = + =src + +# Require a min/specific Python version (comma-separated conditions) +# python_requires = >=3.8 + +# Add here dependencies of your project (line-separated), e.g. requests>=2.2,<3.0. +# Version specifiers like >=2.2,<3.0 avoid problems due to API changes in +# new major versions. This works if the required packages follow Semantic Versioning. +# For more information, check out https://semver.org/. +install_requires = + importlib-metadata; python_version<"3.8" + + +[options.packages.find] +where = src +exclude = + tests + +[options.extras_require] +# Add here additional requirements for extra features, to install with: +# `pip install dolomite-mae[PDF]` like: +# PDF = ReportLab; RXP + +# Add here test requirements (semicolon/line-separated) +testing = + setuptools + pytest + pytest-cov + +[options.entry_points] +# Add here console scripts like: +# console_scripts = +# script_name = dolomite_mae.module:function +# For example: +# console_scripts = +# fibonacci = dolomite_mae.skeleton:run +# And any other entry points, for example: +# pyscaffold.cli = +# awesome = pyscaffoldext.awesome.extension:AwesomeExtension + +[tool:pytest] +# Specify command line options as you would do when invoking pytest directly. +# e.g. --cov-report html (or xml) for html/xml output or --junitxml junit.xml +# in order to write a coverage file that can be read by Jenkins. +# CAUTION: --cov flags may prohibit setting breakpoints while debugging. +# Comment those flags to avoid this pytest issue. +addopts = + --cov dolomite_mae --cov-report term-missing + --verbose +norecursedirs = + dist + build + .tox +testpaths = tests +# Use pytest markers to select/deselect specific tests +# markers = +# slow: mark tests as slow (deselect with '-m "not slow"') +# system: mark end-to-end system tests + +[devpi:upload] +# Options for the devpi: PyPI server and packaging tool +# VCS export must be deactivated since we are using setuptools-scm +no_vcs = 1 +formats = bdist_wheel + +[flake8] +# Some sane defaults for the code style checker flake8 +max_line_length = 88 +extend_ignore = E203, W503 +# ^ Black-compatible +# E203 and W503 have edge cases handled by black +exclude = + .tox + build + dist + .eggs + docs/conf.py + +[pyscaffold] +# PyScaffold's parameters when the project was created. +# This will be used when updating. Do not change! +version = 4.5 +package = dolomite_mae +extensions = + markdown diff --git a/setup.py b/setup.py new file mode 100644 index 0000000..8703acd --- /dev/null +++ b/setup.py @@ -0,0 +1,21 @@ +""" + Setup file for dolomite-mae. + Use setup.cfg to configure your project. + + This file was generated with PyScaffold 4.5. + PyScaffold helps you to put up the scaffold of your new Python project. + Learn more under: https://pyscaffold.org/ +""" +from setuptools import setup + +if __name__ == "__main__": + try: + setup(use_scm_version={"version_scheme": "no-guess-dev"}) + except: # noqa + print( + "\n\nAn error occurred while building the project, " + "please ensure you have the most updated version of setuptools, " + "setuptools_scm and wheel with:\n" + " pip install -U setuptools setuptools_scm wheel\n\n" + ) + raise diff --git a/src/dolomite_mae/__init__.py b/src/dolomite_mae/__init__.py new file mode 100644 index 0000000..89ea05f --- /dev/null +++ b/src/dolomite_mae/__init__.py @@ -0,0 +1,16 @@ +import sys + +if sys.version_info[:2] >= (3, 8): + # TODO: Import directly (no need for conditional) when `python_requires = >= 3.8` + from importlib.metadata import PackageNotFoundError, version # pragma: no cover +else: + from importlib_metadata import PackageNotFoundError, version # pragma: no cover + +try: + # Change here if project is renamed and does not equal the package name + dist_name = "dolomite-mae" + __version__ = version(dist_name) +except PackageNotFoundError: # pragma: no cover + __version__ = "unknown" +finally: + del version, PackageNotFoundError diff --git a/src/dolomite_mae/skeleton.py b/src/dolomite_mae/skeleton.py new file mode 100644 index 0000000..e37b385 --- /dev/null +++ b/src/dolomite_mae/skeleton.py @@ -0,0 +1,149 @@ +""" +This is a skeleton file that can serve as a starting point for a Python +console script. To run this script uncomment the following lines in the +``[options.entry_points]`` section in ``setup.cfg``:: + + console_scripts = + fibonacci = dolomite_mae.skeleton:run + +Then run ``pip install .`` (or ``pip install -e .`` for editable mode) +which will install the command ``fibonacci`` inside your current environment. + +Besides console scripts, the header (i.e. until ``_logger``...) of this file can +also be used as template for Python modules. + +Note: + This file can be renamed depending on your needs or safely removed if not needed. + +References: + - https://setuptools.pypa.io/en/latest/userguide/entry_point.html + - https://pip.pypa.io/en/stable/reference/pip_install +""" + +import argparse +import logging +import sys + +from dolomite_mae import __version__ + +__author__ = "Jayaram Kancherla" +__copyright__ = "Jayaram Kancherla" +__license__ = "MIT" + +_logger = logging.getLogger(__name__) + + +# ---- Python API ---- +# The functions defined in this section can be imported by users in their +# Python scripts/interactive interpreter, e.g. via +# `from dolomite_mae.skeleton import fib`, +# when using this Python module as a library. + + +def fib(n): + """Fibonacci example function + + Args: + n (int): integer + + Returns: + int: n-th Fibonacci number + """ + assert n > 0 + a, b = 1, 1 + for _i in range(n - 1): + a, b = b, a + b + return a + + +# ---- CLI ---- +# The functions defined in this section are wrappers around the main Python +# API allowing them to be called directly from the terminal as a CLI +# executable/script. + + +def parse_args(args): + """Parse command line parameters + + Args: + args (List[str]): command line parameters as list of strings + (for example ``["--help"]``). + + Returns: + :obj:`argparse.Namespace`: command line parameters namespace + """ + parser = argparse.ArgumentParser(description="Just a Fibonacci demonstration") + parser.add_argument( + "--version", + action="version", + version=f"dolomite-mae {__version__}", + ) + parser.add_argument(dest="n", help="n-th Fibonacci number", type=int, metavar="INT") + parser.add_argument( + "-v", + "--verbose", + dest="loglevel", + help="set loglevel to INFO", + action="store_const", + const=logging.INFO, + ) + parser.add_argument( + "-vv", + "--very-verbose", + dest="loglevel", + help="set loglevel to DEBUG", + action="store_const", + const=logging.DEBUG, + ) + return parser.parse_args(args) + + +def setup_logging(loglevel): + """Setup basic logging + + Args: + loglevel (int): minimum loglevel for emitting messages + """ + logformat = "[%(asctime)s] %(levelname)s:%(name)s:%(message)s" + logging.basicConfig( + level=loglevel, stream=sys.stdout, format=logformat, datefmt="%Y-%m-%d %H:%M:%S" + ) + + +def main(args): + """Wrapper allowing :func:`fib` to be called with string arguments in a CLI fashion + + Instead of returning the value from :func:`fib`, it prints the result to the + ``stdout`` in a nicely formatted message. + + Args: + args (List[str]): command line parameters as list of strings + (for example ``["--verbose", "42"]``). + """ + args = parse_args(args) + setup_logging(args.loglevel) + _logger.debug("Starting crazy calculations...") + print(f"The {args.n}-th Fibonacci number is {fib(args.n)}") + _logger.info("Script ends here") + + +def run(): + """Calls :func:`main` passing the CLI arguments extracted from :obj:`sys.argv` + + This function can be used as entry point to create console scripts with setuptools. + """ + main(sys.argv[1:]) + + +if __name__ == "__main__": + # ^ This is a guard statement that will prevent the following code from + # being executed in the case someone imports this file instead of + # executing it as a script. + # https://docs.python.org/3/library/__main__.html + + # After installing your project with pip, users can also run your Python + # modules as scripts via the ``-m`` flag, as defined in PEP 338:: + # + # python -m dolomite_mae.skeleton 42 + # + run() diff --git a/tests/conftest.py b/tests/conftest.py new file mode 100644 index 0000000..aebc7cd --- /dev/null +++ b/tests/conftest.py @@ -0,0 +1,10 @@ +""" + Dummy conftest.py for dolomite_mae. + + If you don't know what this is for, just leave it empty. + Read more about conftest.py under: + - https://docs.pytest.org/en/stable/fixture.html + - https://docs.pytest.org/en/stable/writing_plugins.html +""" + +# import pytest diff --git a/tests/test_skeleton.py b/tests/test_skeleton.py new file mode 100644 index 0000000..068147c --- /dev/null +++ b/tests/test_skeleton.py @@ -0,0 +1,25 @@ +import pytest + +from dolomite_mae.skeleton import fib, main + +__author__ = "Jayaram Kancherla" +__copyright__ = "Jayaram Kancherla" +__license__ = "MIT" + + +def test_fib(): + """API Tests""" + assert fib(1) == 1 + assert fib(2) == 1 + assert fib(7) == 13 + with pytest.raises(AssertionError): + fib(-10) + + +def test_main(capsys): + """CLI Tests""" + # capsys is a pytest fixture that allows asserts against stdout/stderr + # https://docs.pytest.org/en/stable/capture.html + main(["7"]) + captured = capsys.readouterr() + assert "The 7-th Fibonacci number is 13" in captured.out diff --git a/tox.ini b/tox.ini new file mode 100644 index 0000000..69f8159 --- /dev/null +++ b/tox.ini @@ -0,0 +1,93 @@ +# Tox configuration file +# Read more under https://tox.wiki/ +# THIS SCRIPT IS SUPPOSED TO BE AN EXAMPLE. MODIFY IT ACCORDING TO YOUR NEEDS! + +[tox] +minversion = 3.24 +envlist = default +isolated_build = True + + +[testenv] +description = Invoke pytest to run automated tests +setenv = + TOXINIDIR = {toxinidir} +passenv = + HOME + SETUPTOOLS_* +extras = + testing +commands = + pytest {posargs} + + +# # To run `tox -e lint` you need to make sure you have a +# # `.pre-commit-config.yaml` file. See https://pre-commit.com +# [testenv:lint] +# description = Perform static analysis and style checks +# skip_install = True +# deps = pre-commit +# passenv = +# HOMEPATH +# PROGRAMDATA +# SETUPTOOLS_* +# commands = +# pre-commit run --all-files {posargs:--show-diff-on-failure} + + +[testenv:{build,clean}] +description = + build: Build the package in isolation according to PEP517, see https://github.com/pypa/build + clean: Remove old distribution files and temporary build artifacts (./build and ./dist) +# https://setuptools.pypa.io/en/stable/build_meta.html#how-to-use-it +skip_install = True +changedir = {toxinidir} +deps = + build: build[virtualenv] +passenv = + SETUPTOOLS_* +commands = + clean: python -c 'import shutil; [shutil.rmtree(p, True) for p in ("build", "dist", "docs/_build")]' + clean: python -c 'import pathlib, shutil; [shutil.rmtree(p, True) for p in pathlib.Path("src").glob("*.egg-info")]' + build: python -m build {posargs} +# By default, both `sdist` and `wheel` are built. If your sdist is too big or you don't want +# to make it available, consider running: `tox -e build -- --wheel` + + +[testenv:{docs,doctests,linkcheck}] +description = + docs: Invoke sphinx-build to build the docs + doctests: Invoke sphinx-build to run doctests + linkcheck: Check for broken links in the documentation +passenv = + SETUPTOOLS_* +setenv = + DOCSDIR = {toxinidir}/docs + BUILDDIR = {toxinidir}/docs/_build + docs: BUILD = html + doctests: BUILD = doctest + linkcheck: BUILD = linkcheck +deps = + -r {toxinidir}/docs/requirements.txt + # ^ requirements.txt shared with Read The Docs +commands = + sphinx-build --color -b {env:BUILD} -d "{env:BUILDDIR}/doctrees" "{env:DOCSDIR}" "{env:BUILDDIR}/{env:BUILD}" {posargs} + + +[testenv:publish] +description = + Publish the package you have been developing to a package index server. + By default, it uses testpypi. If you really want to publish your package + to be publicly accessible in PyPI, use the `-- --repository pypi` option. +skip_install = True +changedir = {toxinidir} +passenv = + # See: https://twine.readthedocs.io/en/latest/ + TWINE_USERNAME + TWINE_PASSWORD + TWINE_REPOSITORY + TWINE_REPOSITORY_URL +deps = twine +commands = + python -m twine check dist/* + python -m twine upload {posargs:--repository {env:TWINE_REPOSITORY:testpypi}} dist/*