diff --git a/.github/ISSUE_TEMPLATE/i-t-bug-report.md b/.github/ISSUE_TEMPLATE/i-t-bug-report.md index 1c0c3a6..828b2fd 100644 --- a/.github/ISSUE_TEMPLATE/i-t-bug-report.md +++ b/.github/ISSUE_TEMPLATE/i-t-bug-report.md @@ -7,19 +7,26 @@ assignees: jordanpadams --- -**Describe the bug** +## Describe the bug + A clear and concise description of what the bug is. -**Expected behavior** + +## Expected behavior + A clear and concise description of what you expected to happen. -**Test Data** + +## Test Data + Attach test data here -**Related Test Case(s)** +## Related Test Case(s) + Document related test cases here -**Related issues** +## Related issues + Reference relates issues here, e.g. * for issues in this repo: `#1` (remove back ticks) * for issues in other repos: NASA-PDS/my_repo#1, NASA-PDS/her_repo#2 diff --git a/.github/workflows/unstable-cicd.yaml b/.github/workflows/unstable-cicd.yaml index 1113409..cf61af1 100644 --- a/.github/workflows/unstable-cicd.yaml +++ b/.github/workflows/unstable-cicd.yaml @@ -2,7 +2,7 @@ # ================================================= # # Note: for this workflow to succeed, the following secrets must be installed -# in the repository: +# in the repository (or inherited from the repository's organization): # # ``ADMIN_GITHUB_TOKEN`` # A personal access token of a user with collaborator or better access to @@ -51,7 +51,7 @@ jobs: lfs: true - name: 🤠 Roundup - uses: NASA-PDS/roundup-action@master + uses: NASA-PDS/roundup-action@dev with: assembly: unstable env: diff --git a/.gitignore b/.gitignore index 6133dee..0943c11 100644 --- a/.gitignore +++ b/.gitignore @@ -1,15 +1,23 @@ +# Python build, virtual environments, and buildouts venv __pycache__/ dist/ build/ -.idea/ -*.sublime-workspace *.egg-info +.*.cfg +develop-eggs/ +.python-eggs/ +.eggs/ +pip-selfcheck.json + +# Python testing artifacts +.coverage +htmlcov # Object files *.o *.pkl -*.pyc +*.py[ocd] # Libraries *.lib @@ -20,15 +28,20 @@ build/ *.project *.classpath -# IntelliJ files +# Editor support .idea/ *.iml +.vscode +*.sublime-* + # Shared objects (inc. Windows DLLs) *.dll *.so *.so.* *.dylib +lib/ +lib64/ # Executables *.exe @@ -37,10 +50,22 @@ build/ # Temporary files *~ +.*.swp +var/ # other stuff +*.log *.xpr -*.swp -/bin/ +bin/ .*.swp -*.sublime-* + +# OS-specific artifacts +.DS_Store +._* + +# Exclusions +!.coveragerc +!.editorconfig +!.gitattributes +!.gitignore +!.gitkeep diff --git a/CHANGELOG.md b/CHANGELOG.md index e6cb181..c5bf0a2 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,3 +1,3 @@ # Change Log -Use some automated software like [Github Changelog Generator](https://github.com/github-changelog-generator/github-changelog-generator) to update this CHANGELOG. +The [Roundup Action](https://github.com/NASA-PDS/roundup-action) takes care of updating the change log automatically. diff --git a/MANIFEST.in b/MANIFEST.in index 28c1a4a..2ba4455 100644 --- a/MANIFEST.in +++ b/MANIFEST.in @@ -1,5 +1,6 @@ +graft src include versioneer.py -include my_pds_module/_version.py +global-exclude *.py[cod] # Include package-level files and directories here; e.g.: # @@ -7,4 +8,4 @@ include my_pds_module/_version.py # exclude *.webp # graft spice-kernels # prune my_pds_module/obsolete-dir -# global-exclude *.py[cod] +# global-exclude *.log diff --git a/NOTICE.txt b/NOTICE.txt index bab58e8..d82a52e 100644 --- a/NOTICE.txt +++ b/NOTICE.txt @@ -1,6 +1,6 @@ PDS XYZ Tool (update licensing below per specific organization) -Copyright 2020, California Institute of Technology ("Caltech"). +Copyright 2021, California Institute of Technology ("Caltech"). U.S. Government sponsorship acknowledged. All rights reserved. diff --git a/README.md b/README.md index 59298de..ba925a6 100644 --- a/README.md +++ b/README.md @@ -1,59 +1,49 @@ -# pds-template-python -Template repository for PDS python developments. +# pds-template-repo-python -This repository aims at being a base for new python repository used in PDS. +This is the template repository for PDS's Python projects. -It guides developers to ease the initialization of a project and recommends preferred options to standardize developments and ease maintenance. +This repository aims at being a base for new python repositories used in PDS. It guides developers to ease the initialization of a project and recommends preferred options to standardize developments and ease maintenance. Simply click the Use this template button ↑ (or use [this hyperlink](https://github.com/NASA-PDS/pds-template-repo-python/generate)). -## Prerequisites -Any system wide requirements (brew install, apt-get install or yum install ...) +## Prerequisites -**Python3** should be used. +Include any system-wide requirements (`brew install`, `apt-get install`, `yum install`, …) **Python 3** should be used regardless as [Python 2 reached end-of-life on January 1st, 2020](https://pythonclock.org/). -## User quickstart +## User Quickstart -Install +Install with: pip install my_pds_module -Configure +If possible, make it so that your program works out of the box without any additional configuration—but see the [Configuration](###configuration) section for details. -Update local configuration files is relevant. Ideally a default configuration should work (see [Configuration](###configuration) for detail). +To execute, run: -Use (command line or web service url): + (put your run commands here) - ... +## Development -## Developers - -**PyCharm** IDE is useful for complex development project. +To develop this project, use your favorite text editor, or an integrated development environment with Python support, such as [PyCharm](https://www.jetbrains.com/pycharm/). ### Packaging -To isolate and be able to re-produce the environment for the project, we use virtualenv: +To isolate and be able to re-produce the environment for this package, you should use a [Python Virtual Environment](https://docs.python.org/3/tutorial/venv.html). To do so, run: python -m venv venv - source venv/bin/activate - - -Dependencies for development are stored in file requirements.txt, they are installed in the virtualenv as follow: - - pip install -r requirements.txt - -Use setup tools to package your code: +Then exclusively use `venv/bin/python`, `venv/bin/pip`, etc. (It is no longer recommended to use `venv/bin/activate`.) - pip install setuptools +Dependencies for development are stored in requirements.txt; they are installed into the virtual environment as follows: + venv/bin/pip install --requirement requirements.txt -All the source code is in a sub-directory named after the developed module, for example my_pds_module. -If the project is complex, we might have different sub-modules in this directory. +All the source code is in a sub-directory under `src`. + +You should update the `setup.py` file with: -Update the setup.py file: - name of your module - version - license, default apache, update if needed @@ -64,96 +54,99 @@ Update the setup.py file: - install_requires, add the dependencies of you module - entry_points, when your module can be called in command line, this helps to deploy command lines entry points pointing on scripts in your module -You can update the setup.cfg file which describes how setup.py can be called, with which directives and options. This is useful for pypi publication. +Eventually, we should move to putting everything into `setup.cfg`, as having package metadata in `setup.py` is passé. For the packaging details, see https://packaging.python.org/tutorials/packaging-projects/ as a reference. + ### Configuration -It is convenient to use ConfigParser package to manage configuration. -It allows to have a default configuration which can be overwritten by the user in a specific file in their environment. -See https://pymotw.com/2/ConfigParser/ +It is convenient to use ConfigParser package to manage configuration. It allows a default configuration which can be overwritten by the user in a specific file in their environment. See https://pymotw.com/2/ConfigParser/ For example: - candidates = ['my_pds_module.ini', - 'my_pds_module.ini.default'] + candidates = ['my_pds_module.ini', 'my_pds_module.ini.default'] found = parser.read(candidates) + ### Logs You should not use `print()`vin the purpose of logging information on the execution of your code. Depending on where the code runs these information could be redirected to specific log files. -To make that work, have a the beginning of your python file: +To make that work, start each Python file with: ```python import logging -logging.basicConfig(level=logging.INFO) logger = logging.getLogger(__name__) ``` To log a message: logger.info("my message") + +In your `main` routine, include: + + logging.basicConfig(level=logging.INFO) + +to get a basic logging system configured. -### Code style +### Code Style + +So that your code is readable, you should comply with the [PEP8 style guide](https://www.python.org/dev/peps/pep-0008/). It is automatically enforced in PyCharm IDE. -So that your code is readable, you must comply with the PEP8 style guide, see https://www.python.org/dev/peps/pep-0008/ +Note that several PEP8 guidelines are rather old fashioned; trust your judgment. -It is automatically enforced in PyCharm IDE. -### Recommended libraries +### Recommended Libraries Python offers a large variety of libraries. In PDS scope, for the most current usage we should use: -| Library | Usage | -|------------|-----------------------------| -| configparser | manage and parse configuration files | -| argparse | command line argument documentation and parsing | -| requests | interact with web APIs | -| lxml | read/write XML files | -| json | read/write JSON files | -| pyyaml | read/write YAML files | -| pystache | generate files from templates | +| Library | Usage | +|--------------|------------------------------------------------ | +| configparser | manage and parse configuration files | +| argparse | command line argument documentation and parsing | +| requests | interact with web APIs | +| lxml | read/write XML files | +| json | read/write JSON files | +| pyyaml | read/write YAML files | +| pystache | generate files from templates | + +Some of these are built into Python 3; others are open source add-ons you can include in your `requirements.txt`. ### Tests +This section describes testing for your package. + + #### Unit tests -Your project should have built-in unit tests and validation tests. +Your project should have built-in unit tests, functional, validation, acceptance, etc., tests. -The package to be used for unit testing is unittest, see https://docs.python.org/3/library/unittest.html +For unit testing, check out the [unittest](https://docs.python.org/3/library/unittest.html) module, built into Python 3. -Tests objects must be in packages 'test' subdirectories or preferably in project 'tests' directory which mirrors the project package structure. +Tests objects should be in packages `test` modules or preferably in project 'tests' directory which mirrors the project package structure. Unit tests are launched with command: python setup.py test -#### Integration/behavioral tests -One shoud use the `behave package` and push the test results to testrail. +#### Integration/Behavioral Tests -See example in https://github.com/NASA-PDS/pds-doi-service#behavioral-testing +One should use the `behave package` and push the test results to "testrail". -## Build +See an example in https://github.com/NASA-PDS/pds-doi-service#behavioral-testing-for-integration--testing - pip install wheel - python sdist bdist_wheel - -### Publication - -You can publish your module on PyPi (you need a pypi account): - - pip install twine - twine upload dist/* - -You can also use github actions, see example provided in `.github/workflows/publish.yml.example` +## Build + pip install wheel + python setup.py sdist bdist_wheel +### Publication +NASA PDS packages can publish automatically using the [Roundup Action](https://github.com/NASA-PDS/roundup-action), which leverages GitHub Actions to perform automated continuous integration and continuous delivery. A default workflow that includes the Roundup is provided in the `.github/workflows/unstable-cicd.yaml` file. (Unstable here means an interim release.) diff --git a/SECURITY.md b/SECURITY.md index 55c7474..73d76fc 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -1,16 +1,20 @@ # Security Policy +This document describes the security policy of this package. + + ## Supported Versions -Use this section to tell people about which versions of your project are -currently being supported with security updates. +Use this section to tell people about which versions of your project are currently being supported with security updates. -| Version | Supported | -| ------- | ------------------ | +| Version | Supported | +| -------- | ------------------ | | 1.18.2 | :white_check_mark: | | 1.17.5 | :white_check_mark: | -| < 1.17.5 | :x: | +| < 1.17.5 | :x: | + ## Reporting a Vulnerability -Please create a new issue using the [Vulnerability Issue template](https://github.com/NASA-PDS-Incubator/validate/issues/new?assignees=jordanpadams&labels=triage-needed%2C+security&template=vulnerability-issue.md&title=%5BSECURITY%5D+Title+Here) +To report a vulnerability in this package, please [submit a new isssue using the Vulnerability Issue template](https://github.com/NASA-PDS-Incubator/validate/issues/new?assignees=jordanpadams&labels=triage-needed%2C+security&template=vulnerability-issue.md&title=%5BSECURITY%5D+Title+Here). + diff --git a/docs/source/index.rst b/docs/source/index.rst index 9fc2426..83e7916 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -1,9 +1,8 @@ Overview ======== -Welcome to you PDS template site! Have Fun! +Welcome to your PDS template package! Have Fun! --------------- Sitemap diff --git a/docs/source/support/contact.rst b/docs/source/support/contact.rst index 1f49d7b..afe7498 100644 --- a/docs/source/support/contact.rst +++ b/docs/source/support/contact.rst @@ -1,4 +1,4 @@ Contact Us ========== -Feel free to contact us the `PDS Operator `_ for any additional questions, comments or concerns. \ No newline at end of file +Feel free to contact us the `PDS Operator `_ for any additional questions, comments or concerns. diff --git a/docs/source/support/contribute.rst b/docs/source/support/contribute.rst index 90452f1..335f05e 100644 --- a/docs/source/support/contribute.rst +++ b/docs/source/support/contribute.rst @@ -3,17 +3,15 @@ Contribute We are always looking for community input into our software. Feel free to contribute to the PDS repos: -* Contribute to this documentation: https://github.com/NASA-PDS/NASA-PDS.github.io -* Contribute to a specific software project: https://github.com/NASA-PDS +• Contribute to this documentation: https://github.com/NASA-PDS/NASA-PDS.github.io +• Contribute to a specific software project: https://github.com/NASA-PDS ----- Request a New Tool / Service ============================ Feel free to propose a new idea to our `Engineering Node Operations repo `_ and we will triage it appropriately. ----- Report a Bug ============ diff --git a/docs/source/support/forum.rst b/docs/source/support/forum.rst deleted file mode 100644 index 31c3d81..0000000 --- a/docs/source/support/forum.rst +++ /dev/null @@ -1,4 +0,0 @@ -OpenPlanetary Forum -=================== - -We also have a user forum on the OpenPlanetary Forum (TBD link to forum) and a `#pds4 OpenPlanetary Slack channel `_ (note: you must become an `OpenPlanetary Member `_ to join the Slack Org). \ No newline at end of file diff --git a/requirements.txt b/requirements.txt index e37f295..e69de29 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,3 +0,0 @@ -sphinx==3.1.1 -sphinx-rtd-theme==0.5.0 -sphinxemoji diff --git a/setup.py b/setup.py index 20d1119..e3d0997 100644 --- a/setup.py +++ b/setup.py @@ -2,37 +2,59 @@ import setuptools, versioneer -with open("README.md", "r") as fh: + +# Package Metadata +# ---------------- +# +# Replace values below with what's appropriate for your package: + +name = 'my-package' +description = 'A short description, about 100–120 characters' +keywords = ['pds', 'planetary data', 'various', 'other', 'keywords'] +zip_safe = True +namespace_packages = ['pds'] +extras_require = {} +entry_points = {} + + +# You can find the vocabulary for these at https://pypi.org/classifiers/ +classifiers = [ + 'Programming Language :: Python :: 3', + 'License :: OSI Approved :: Apache Software License', + 'Operating System :: OS Independent', +] + +# Below here, you shouldn't have to change anything: + +with open('README.md', 'r') as fh: long_description = fh.read() with open('requirements.txt', 'r') as f: pip_requirements = f.readlines() - + setuptools.setup( - name="my_pds_module", # Replace with your own package name + name=name, version=versioneer.get_version(), - license="apache-2.0", - author="pds ", - author_email="pds_operator@jpl.nasa.gov", - description="short description of my pds module, less than 100–120 characters", + license='apache-2.0', # There's almost no standardization about what goes here, even amongst ALv2 projects + author='PDS', + author_email='pds_operator@jpl.nasa.gov', + description=description, long_description=long_description, - long_description_content_type="text/markdown", - url="https://github.com/NASA-PDS/pds-template-python", - download_url="https://github.com/NASA-PDS/pds-template-python/releases/download/....", - packages=setuptools.find_packages(), - keywords=['pds', 'other keywords'], - - classifiers=[ - "Programming Language :: Python :: 3", - "License :: OSI Approved :: Apache Software License", - "Operating System :: OS Independent", - ], + long_description_content_type='text/markdown', + url='https://github.com/NASA-PDS/' + name, + download_url='https://github.com/NASA-PDS/' + name + '/releases/download/…', + packages=setuptools.find_packages('src'), + include_package_data=True, + zip_safe=zip_safe, # Change this if you need + namespace_packages=namespace_packages, + package_dir={'': 'src'}, + keywords=keywords, + classifiers=classifiers, python_requires='>=3.6', install_requires=pip_requirements, - entry_points={ - 'console_scripts': ['snapshot-release=pds_github_util:snapshot_release.main'], - }, + entry_points=entry_points, + extras_require=extras_require, cmdclass=versioneer.get_cmdclass() ) diff --git a/src/pds/__init__.py b/src/pds/__init__.py new file mode 100644 index 0000000..786e7fe --- /dev/null +++ b/src/pds/__init__.py @@ -0,0 +1,5 @@ +# -*- coding: utf-8 -*- + +'''PDS Namespace''' + +__import__('pkg_resources').declare_namespace(__name__) diff --git a/my_pds_module/__init__.py b/src/pds/my_pds_module/__init__.py similarity index 78% rename from my_pds_module/__init__.py rename to src/pds/my_pds_module/__init__.py index 473ab4e..9970c48 100644 --- a/my_pds_module/__init__.py +++ b/src/pds/my_pds_module/__init__.py @@ -11,4 +11,4 @@ # For future consideration: # # - Other metadata (__docformat__, __copyright__, etc.) -# - Namespace packages? +# - N̶a̶m̶e̶s̶p̶a̶c̶e̶ ̶p̶a̶c̶k̶a̶g̶e̶s̶ we got this diff --git a/my_pds_module/_version.py b/src/pds/my_pds_module/_version.py similarity index 100% rename from my_pds_module/_version.py rename to src/pds/my_pds_module/_version.py