Merge branch 'rprechelt-python-package' into 'master'

Add basic Python package skeleton.

See merge request !256

.gitlab-ci.yml

@@ -28,6 +28,7 @@ stages:
   - build
   - test
   - build_test
+  - python
   - example
   - build_test_example
   - install
@@ -616,3 +617,36 @@ sanity:
     untracked: true
     policy: pull
     key: "${CI_COMMIT_REF_SLUG}-gcc"
+
+
+
+##########################################################
+# template for all Python jobs
+.python:
+  stage: python
+  tags:
+    - corsika
+  script:
+    - cd ${CI_PROJECT_DIR}/Python  # change into the Python directory
+    - pip install --user -e '.[test]'  # install the package + test deps
+    - make all 2&>1 | tee python-test.log  # this runs all of the Python tests
+    - cd ${CI_PROJECT_DIR}  # reset the directory
+  artifacts:
+    when: always
+    expire_in: 1 year
+    paths:
+      - ${CI_PROJECT_DIR}/Python/python-test.log
+
+# we now configure the jobs for the three
+# supported Python versions
+python-3.6:
+  extends: .python
+  image: python:3.6
+
+python-3.7:
+  extends: .python
+  image: python:3.7
+
+python-3.8:
+  extends: .python
+  image: python:3.8

Python/.gitignore

+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+pip-wheel-metadata/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# static files generated from Django application using `collectstatic`
+media
+static

Python/MANIFEST.in

+include README.md LICENSE
+recursive-include corsika *
+recursive-include scripts *
+recursive-include examples *

Python/Makefile

+##
+# ##
+# corsika
+#
+# @file
+
+# find python3
+PYTHON=`which python3`
+
+# our testing targets
+.PHONY: tests flake black isort all
+
+all: mypy isort black flake tests
+
+tests:
+	${PYTHON} -m pytest --cov=corsika tests
+
+flake:
+	${PYTHON} -m flake8 corsika
+
+black:
+	${PYTHON} -m black -t py37 corsika tests
+
+isort:
+	${PYTHON} -m isort --atomic corsika tests
+
+mypy:
+	${PYTHON} -m mypy corsika
+
+# end

Python/README.md

+# Python for CORSIKA8
+
+![License](https://img.shields.io/badge/license-GPL3-blue)
+![Python](https://img.shields.io/badge/python-3.6%20%7C%203.7%20%7C%203.8-blue)
+[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
+
+## Installation
+
+To install the CORSIKA 8 Python library, you will need Python >= 3.6. The below
+instructions are assuming that `python` refers to Python 3.\*. If `python` still
+refers to Python 2.\*, please replace `python` with `python3` and `pip` with
+`pip3`.
+
+To install this package, change into the `corsika/Python` directory and run
+
+    pip install --user -e .
+
+You can verify that the installation was successful by trying to import `corsika`
+
+    python -c 'import corsika'
+
+## Running the Tests
+    
+If you wish to develop new features in `corsika`, you will also need to install
+some additional dependencies so you can run our unit tests. These can be
+installed with
+
+    pip install --user -e '.[test]'
+
+Once that is completed, you can run the unit tests directory from the `corsika` directory
+
+    python -m pytest tests
+
+## Development Guide
+
+`corsika` is a type Python package with type-checking using
+[Mypy](mypy-lang.org) and all code is formatted with the
+[Black](https://black.readthedocs.io/en/stable/) formatter.
+
+All code must pass these checks, as well as several others, before it can be
+merged into CORSIKA. A `Makefile` is provided to simplify running these in
+tasks.
+
+    make mypy   # this will run the mypy type checker
+    
+    make isort  # this will automatically sort `import` statements
+    
+    make black  # this will automatically format your code
+    
+    make flake  # this checks that all code passes our linting rules
+    
+    make tests  # this runs our test suite
+    
+Lastly, we provide an `all` target that runs *all* of the above in the sequence shown above:
+
+    make all  # run all of the above tests

Python/corsika/__init__.py

+"""
+ (c) Copyright 2018 CORSIKA Project, corsika-project@lists.kit.edu
+
+ This software is distributed under the terms of the GNU General Public
+ Licence version 3 (GPL Version 3). See file LICENSE for a full version of
+ the license.
+"""
+
+__version__: str = "8.0.0-alpha"

Python/setup.cfg

+[flake8]
+# use a slightly longer line to be consistent with black
+max-line-length = 88
+
+# E231 is missing whitespace after a comma
+# this contradicts the black formatting rules
+# and therefore creates spurious errors
+ignore = E231
+
+# we set various directories we want to exclude
+exclude =
+    # Don't bother checking in cache directories
+    __pycache__
+
+
+[isort]
+# use parenthesis for multi-line imports
+use_parentheses = true
+
+
+[mypy]
+# the primary Python version
+python_version = 3.7
+
+# allow returning Any
+# this creates excessive errors when using libraries
+# that don't have MyPy typing support
+warn_return_any = False
+
+# don't allow untyped functions
+disallow_untyped_defs = True
+
+# warn if any part of this config is mispelled
+warn_unused_configs = True
+
+# warn for missing type information
+warn_incomplete_stub = True
+
+# warn us if we don't return from a function explicitly
+warn_no_return = True
+
+# use incremental typing to speed things up
+incremental = True
+
+# show error contexts
+show_error_context = True
+
+# and show the column numbers for errors
+show_column_numbers = True
+
+# ignore missing types for setuptools
+[mypy-setuptools.*]
+ignore_missing_imports = True
+
+# ignore missing types for numpy
+[mypy-numpy.*]
+ignore_missing_imports = True
+
+# ignore missing types for matplotlib
+[mypy-matplotlib.*]
+ignore_missing_imports = True

Python/setup.py

+from os import path
+from setuptools import setup
+
+# the stereo version
+__version__ = "8.0.0-alpha"
+
+# get the absolute path of this project
+here = path.abspath(path.dirname(__file__))
+
+# Get the long description from the README file
+with open(path.join(here, "README.md"), encoding="utf-8") as f:
+    long_description = f.read()
+
+# the standard setup info
+setup(
+    name="corsika",
+    version=__version__,
+    description="A Python package for working with CORSIKA 8",
+    long_description=long_description,
+    long_description_content_type="text/markdown",
+    url="https://gitlab.ikp.kit.edu/AirShowerPhysics/corsika",
+    author="CORSIKA 8 Collaboration",
+    author_email="corsika-devel@lists.kit.edu",
+    classifiers=[
+        "Development Status :: 3 - Alpha",
+        "Intended Audience :: Science/Research",
+        "Topic :: Scientific/Engineering :: Physics",
+        "Programming Language :: Python :: 3.6",
+        "Programming Language :: Python :: 3.7",
+        "Programming Language :: Python :: 3.8",
+    ],
+    keywords=["cosmic ray", "physics", "astronomy", "simulation"],
+    packages=["corsika"],
+    python_requires=">=3.6*, <4",
+    install_requires=["numpy", "pyyaml",],
+    extras_require={
+        "test": [
+            "pytest",
+            "black",
+            "mypy",
+            "isort",
+            "coverage",
+            "pytest-cov",
+            "flake8",
+        ],
+    },
+    scripts=[],
+    project_urls={"code": "https://gitlab.ikp.kit.edu/AirShowerPhysics/corsika"},
+    include_package_data=True,
+)

Python/tests/test_corsika.py

+"""
+ (c) Copyright 2018 CORSIKA Project, corsika-project@lists.kit.edu
+
+ This software is distributed under the terms of the GNU General Public
+ Licence version 3 (GPL Version 3). See file LICENSE for a full version of
+ the license.
+"""
+import corsika
+
+
+def test_corsika_version() -> None:
+    """
+    Check the current CORSIKA version.
+    """
+    assert corsika.__version__ == "8.0.0-alpha"