diff --git a/.coveralls.yml b/.coveralls.yml new file mode 100644 index 00000000..4ecf44e5 --- /dev/null +++ b/.coveralls.yml @@ -0,0 +1,2 @@ +service_name: github +# repo_token: YOURTOKENHERE diff --git a/.cruft.json b/.cruft.json new file mode 100644 index 00000000..bb50722a --- /dev/null +++ b/.cruft.json @@ -0,0 +1,27 @@ +{ + "template": "https://github.com/Ouranosinc/cookiecutter-pypackage", + "commit": "8e44c8f85d93b68ac036b79f56c90846da689f46", + "checkout": null, + "context": { + "cookiecutter": { + "full_name": "Thomas-Charles Fortier Filion", + "email": "tcff_hydro@outlook.com", + "github_username": "TC-FF", + "project_name": "xHydro", + "project_slug": "xhydro", + "project_short_description": "Hydrological analysis library built with xarray", + "pypi_username": "TC-FF", + "version": "0.1.2", + "use_pytest": "y", + "use_black": "y", + "add_pyup_badge": "n", + "make_docs": "y", + "command_line_interface": "No command-line interface", + "create_author_file": "y", + "open_source_license": "Apache Software License 2.0", + "generated_with_cruft": "y", + "_template": "https://github.com/Ouranosinc/cookiecutter-pypackage" + } + }, + "directory": null +} diff --git a/.editorconfig b/.editorconfig index d4a2c440..70b87258 100644 --- a/.editorconfig +++ b/.editorconfig @@ -10,6 +10,9 @@ insert_final_newline = true charset = utf-8 end_of_line = lf +[*.{yaml,yml}] +indent_size = 2 + [*.bat] indent_style = tab end_of_line = crlf diff --git a/.github/ISSUE_TEMPLATE/0001-GENERIC-ISSUE-TEMPLATE.yml b/.github/ISSUE_TEMPLATE/0001-GENERIC-ISSUE-TEMPLATE.yml new file mode 100644 index 00000000..2b749e12 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/0001-GENERIC-ISSUE-TEMPLATE.yml @@ -0,0 +1,34 @@ +name: Generic issue template +description: For detailing generic/uncategorized issues in xHydro + +body: + - type: textarea + id: generic-issue + attributes: + label: Generic Issue + description: Please fill in the following information fields as needed. + value: | + * xhydro version: + * Python version: + * Operating System: + + ### Description + + + ### What I Did + + ``` + $ pip install foo --bar + ``` + + ### What I Received + + ``` + Traceback (most recent call last): + File "/path/to/file/script.py", line 3326, in run_code + exec(code_obj, self.user_global_ns, self.user_ns) + File "", line 1, in + 1/0 + ZeroDivisionError: division by zero diff --git a/.github/ISSUE_TEMPLATE/0002-BUG-REPORT.yml b/.github/ISSUE_TEMPLATE/0002-BUG-REPORT.yml new file mode 100644 index 00000000..d597b8b6 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/0002-BUG-REPORT.yml @@ -0,0 +1,44 @@ +name: Bug report +description: Help us improve xHydro +labels: [ "bug" ] + +body: + - type: markdown + attributes: + value: | + Thanks for taking the time to fill out this bug report! + - type: textarea + id: setup-information + attributes: + label: Setup Information + description: | + What software versions are you running? Example: + - xhydro version: 0.55.0-gamma + - Python version: 4.2 + - Operating System: Nutmeg Linux 12.34 | macOS 11.0 "Redmond" + value: | + - xhydro version: + - Python version: + - Operating System: + - type: textarea + id: description + attributes: + label: Description + description: Describe what you were trying to get done. Tell us what happened, what went wrong, and what you expected to happen. + - type: textarea + id: steps-to-reproduce + attributes: + label: Steps To Reproduce + description: Paste the command(s) you ran and the output. If there was a crash, please include the traceback below. + - type: textarea + id: additional-context + attributes: + label: Additional context + description: Add any other context about the problem here. + - type: checkboxes + id: submit-pr + attributes: + label: Contribution + description: Do you intend to submit a fix for this bug? (The xHydro developers will help with code compliance) + options: + - label: I would be willing/able to open a Pull Request to address this bug. diff --git a/.github/ISSUE_TEMPLATE/0003-FEATURE-REQUEST.yml b/.github/ISSUE_TEMPLATE/0003-FEATURE-REQUEST.yml new file mode 100644 index 00000000..9b0872df --- /dev/null +++ b/.github/ISSUE_TEMPLATE/0003-FEATURE-REQUEST.yml @@ -0,0 +1,31 @@ +name: Feature request +description: Suggest an idea for xHydro +labels: [ "enhancement" ] + +body: + - type: markdown + attributes: + value: | + Thanks for taking the time to fill out this feature request! + - type: textarea + id: problem + attributes: + label: Addressing a Problem? + description: Is your feature request related to a problem? Please describe it. + - type: textarea + id: potential-solution + attributes: + label: Potential Solution + description: Describe the solution you'd like to see implemented. + - type: textarea + id: additional-context + attributes: + label: Additional context + description: Add any other context about the feature request here. + - type: checkboxes + id: submit-pr + attributes: + label: Contribution + description: Do you intend to submit a fix for this bug? (The xHydro developers will help with code compliance) + options: + - label: I would be willing/able to open a Pull Request to contribute this feature. diff --git a/.github/ISSUE_TEMPLATE/0004-QUESTION-SUPPORT.yml b/.github/ISSUE_TEMPLATE/0004-QUESTION-SUPPORT.yml new file mode 100644 index 00000000..20720c6f --- /dev/null +++ b/.github/ISSUE_TEMPLATE/0004-QUESTION-SUPPORT.yml @@ -0,0 +1,23 @@ +name: Question/Support +description: Ask for help from the developers +labels: [ "support" ] + +body: + - type: textarea + id: setup-information + attributes: + label: Setup Information + description: | + What software versions are you running? Example: + - xhydro version: 0.55.0-gamma + - Python version: 4.2 + - Operating System: Nutmeg Linux 12.34 | macOS 11.0 "Redmond" + value: | + - xhydro version: + - Python version: + - Operating System: + - type: textarea + id: description + attributes: + label: Context + description: Describe what you were trying to get done. Tell us what happened, what went wrong, and what you expected to happen. diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 00000000..0086358d --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1 @@ +blank_issues_enabled: true diff --git a/.github/workflows/bump-version.yml b/.github/workflows/bump-version.yml index a3814f31..d7881b90 100644 --- a/.github/workflows/bump-version.yml +++ b/.github/workflows/bump-version.yml @@ -9,21 +9,19 @@ on: - .editorconfig - .github/**.yml - .gitignore - - .gitlab-ci.yml - - .gitmodules - .pre-commit-config.yaml - .yamllint.yaml - AUTHORS.rst - CONTRIBUTING.rst - - docs/notebooks + - HISTORY.rst + - MANIFEST.in + - Makefile - docs/*.py - docs/*.rst - - environment-dev.yml + - docs/notebooks + - environment-docs.yml - environment.yml - - CHANGES.rst - - Makefile - - MANIFEST.in - - requirements_upstream.txt + - requirements_dev.txt - setup.cfg - setup.py - tests/**.py @@ -35,11 +33,9 @@ jobs: runs-on: ubuntu-latest steps: - uses: actions/checkout@v3 - with: - persist-credentials: false - uses: actions/setup-python@v4 with: - python-version: "3.x" + python-version: "3.9" - name: Config Commit Bot run: | git config --local user.email "bumpversion[bot]@hydrologie.com" @@ -57,4 +53,4 @@ jobs: with: force: false github_token: ${{ secrets.GITHUB_TOKEN }} - branch: ${{ github.ref }} \ No newline at end of file + branch: ${{ github.ref }} diff --git a/.github/workflows/first_pull_request.yml b/.github/workflows/first_pull_request.yml new file mode 100644 index 00000000..1a1c4827 --- /dev/null +++ b/.github/workflows/first_pull_request.yml @@ -0,0 +1,46 @@ +name: First Pull Request + +on: + pull_request_target: + types: + - opened + +jobs: + welcome: + name: Welcome + runs-on: ubuntu-latest + steps: + - uses: actions/github-script@v6 + with: + script: | + // Get a list of all issues created by the PR opener + // See: https://octokit.github.io/rest.js/#pagination + const creator = context.payload.sender.login + const opts = github.rest.issues.listForRepo.endpoint.merge({ + ...context.issue, + creator, + state: 'all' + }) + const issues = await github.paginate(opts) + + for (const issue of issues) { + if (issue.number === context.issue.number) { + continue + } + + if (issue.pull_request) { + return // Creator is already a contributor. + } + } + + await github.rest.issues.createComment({ + issue_number: context.issue.number, + owner: context.repo.owner, + repo: context.repo.repo, + body: `**Welcome**, new contributor! + + It appears that this is your first Pull Request. To give credit where it's due, we ask that you add your information to the \`AUTHORS.rst\` and \`.zenodo.json\`.: + - [ ] The relevant author information has been added to \`AUTHORS.rst\` and \`.zenodo.json\`. + + Please make sure you've read our [contributing guide](CONTRIBUTING.rst). We look forward to reviewing your Pull Request shortly ✨` + }) diff --git a/.github/workflows/gh-pages.yml b/.github/workflows/gh-pages.yml index 4e78f917..b0836572 100644 --- a/.github/workflows/gh-pages.yml +++ b/.github/workflows/gh-pages.yml @@ -1,4 +1,5 @@ -name: Docs +name: Deploy Documentation + on: push: branches: @@ -6,23 +7,22 @@ on: pull_request: branches: - master + permissions: contents: write + jobs: build-and-deploy: runs-on: ubuntu-latest steps: - name: Checkout πŸ›ŽοΈ - uses: actions/checkout@v2.3.1 # If you're using actions/checkout@v2 you must set persist-credentials to false in most cases for the deployment to work correctly. + uses: actions/checkout@v3 + - uses: mamba-org/setup-micromamba@v1 with: - persist-credentials: false - - uses: conda-incubator/setup-miniconda@v2 - with: - activate-environment: xhydro environment-file: environment.yml - mamba-version: "*" - python-version: "3.10" - auto-activate-base: false + cache-environment: true + create-args: >- + python=3.10 - name: Deploy docs shell: bash -l {0} run: | @@ -30,7 +30,7 @@ jobs: pip install -e . make -C docs html - name: Deploy πŸš€ - uses: JamesIves/github-pages-deploy-action@v4.2.2 + uses: JamesIves/github-pages-deploy-action@v4 with: branch: gh-pages # The branch the action should deploy to. - folder: docs/_build/html # The folder the action should deploy. \ No newline at end of file + folder: docs/_build/html # The folder the action should deploy. diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml new file mode 100644 index 00000000..dc34cd36 --- /dev/null +++ b/.github/workflows/main.yml @@ -0,0 +1,88 @@ +name: xHydro Testing Suite + +on: + push: + branches: + - main + paths-ignore: + - HISTORY.rst + - MANIFEST.in + - README.rst + - setup.cfg + - setup.py + - xhydro/__init__.py + pull_request: + +jobs: + black: + name: Black (Python${{ matrix.python-version }}) + runs-on: ubuntu-latest + strategy: + matrix: + python-version: + - "3.8" + steps: + - name: Cancel previous runs + uses: styfle/cancel-workflow-action@0.11.0 + with: + access_token: ${{ secrets.GITHUB_TOKEN }} + - uses: actions/checkout@v3 + - name: Set up Python${{ matrix.python-version }} + uses: actions/setup-python@v4 + with: + python-version: ${{ matrix.python-version }} + - name: Install tox + run: pip install tox + - name: Run linting suite + run: tox -e black + + test: + name: test-${{ matrix.tox-env }} (Python${{ matrix.python-version }}) + needs: black + runs-on: ubuntu-latest + strategy: + matrix: + include: + - tox-env: "py39" + python-version: "3.9" + - tox-env: "py310" + python-version: "3.10" + - tox-env: "py311" + python-version: "3.11" + steps: + - uses: actions/checkout@v3 + - name: Set up Python${{ matrix.python-version }} + uses: actions/setup-python@v4 + with: + python-version: ${{ matrix.python-version }} +# - name: Install tox +# run: pip install tox +# - name: Test with tox +# run: tox -e ${{ matrix.tox-env }} +# env: +# GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} +# COVERALLS_FLAG_NAME: run-${{ matrix.tox-env }} +# COVERALLS_PARALLEL: true +# COVERALLS_SERVICE_NAME: github + - name: Install xhydro (no dependencies) + run: | + python -m pip install -e . --no-dependencies + - name: Smoke tests + run: | + python -m pip install pytest + pytest + +# FIXME: Needs the Coveralls Pro webhook +# finish: +# needs: +# - test +# runs-on: ubuntu-latest +# container: python:3-slim +# steps: +# - name: Coveralls Finished +# run: | +# pip install --upgrade coveralls +# coveralls --finish +# env: +# GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} +# COVERALLS_SERVICE_NAME: github diff --git a/.github/workflows/publish-pypi.yml b/.github/workflows/publish-pypi.yml index b7e54d46..f54bc32f 100644 --- a/.github/workflows/publish-pypi.yml +++ b/.github/workflows/publish-pypi.yml @@ -1,4 +1,4 @@ -name: "Publish Python 🐍 distributions πŸ“¦ to PyPI" +name: Publish Python 🐍 distributions πŸ“¦ to PyPI on: release: @@ -14,13 +14,15 @@ jobs: - name: Set up Python3 uses: actions/setup-python@v4 with: - python-version: "3.x" + python-version: "3.9" - name: Install packaging libraries - run: pip install setuptools wheel + run: | + pip install setuptools wheel - name: Build a binary wheel and a source tarball - run: python setup.py sdist bdist_wheel + run: | + python setup.py sdist bdist_wheel - name: Publish distribution πŸ“¦ to PyPI uses: pypa/gh-action-pypi-publish@release/v1 with: user: __token__ - password: ${{ secrets.PYPI_API_TOKEN }} \ No newline at end of file + password: ${{ secrets.PYPI_API_TOKEN }} diff --git a/.github/workflows/tag-testpypi.yml b/.github/workflows/tag-testpypi.yml index 782f0fda..4539f1be 100644 --- a/.github/workflows/tag-testpypi.yml +++ b/.github/workflows/tag-testpypi.yml @@ -1,4 +1,4 @@ -name: "Publish Python 🐍 distributions πŸ“¦ to TestPyPI" +name: Publish Python 🐍 distributions πŸ“¦ to TestPyPI on: push: @@ -14,15 +14,17 @@ jobs: - name: Set up Python3 uses: actions/setup-python@v4 with: - python-version: "3.x" + python-version: "3.9" - name: Install packaging libraries - run: pip install setuptools wheel + run: | + pip install setuptools wheel - name: Build a binary wheel and a source tarball - run: python setup.py sdist bdist_wheel + run: | + python setup.py sdist bdist_wheel - name: Publish distribution πŸ“¦ to Test PyPI uses: pypa/gh-action-pypi-publish@release/v1 with: user: __token__ password: ${{ secrets.TEST_PYPI_API_TOKEN }} repository_url: https://test.pypi.org/legacy/ - skip_existing: true \ No newline at end of file + skip_existing: true diff --git a/.gitignore b/.gitignore index 4c915d14..d1bd55df 100644 --- a/.gitignore +++ b/.gitignore @@ -1,3 +1,5 @@ +# XHYDRO-specific + # Byte-compiled / optimized / DLL files __pycache__/ *.py[cod] diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml new file mode 100644 index 00000000..d185ec5b --- /dev/null +++ b/.pre-commit-config.yaml @@ -0,0 +1,83 @@ +default_language_version: + python: python3 + +repos: + - repo: https://github.com/asottile/pyupgrade + rev: v3.4.0 + hooks: + - id: pyupgrade + args: [--py39-plus] + - repo: https://github.com/pre-commit/pre-commit-hooks + rev: v4.4.0 + hooks: + - id: trailing-whitespace + exclude: setup.cfg + - id: end-of-file-fixer + - id: debug-statements + - id: check-json + - id: pretty-format-json + args: [ '--autofix', '--no-ensure-ascii', '--no-sort-keys' ] + - id: check-yaml + args: [ '--allow-multiple-documents' ] + - repo: https://github.com/pre-commit/pygrep-hooks + rev: v1.10.0 + hooks: + - id: rst-inline-touching-normal + - repo: https://github.com/psf/black + rev: 23.3.0 + hooks: + - id: black + exclude: ^docs/ + - repo: https://github.com/pycqa/flake8 + rev: 6.0.0 + hooks: + - id: flake8 + additional_dependencies: [ 'flake8-rst-docstrings' ] + args: ['--config=setup.cfg'] + - repo: https://github.com/psf/black + rev: 23.3.0 + hooks: + - id: black + exclude: ^docs/ + args: [ '--target-version=py39' ] + - repo: https://github.com/PyCQA/isort + rev: 5.12.0 + hooks: + - id: isort + args: ['--settings-file=setup.cfg'] + exclude: ^docs/ + - repo: https://github.com/PyCQA/pydocstyle + rev: 6.3.0 + hooks: + - id: pydocstyle + args: [ '--config=setup.cfg' ] + - repo: https://github.com/keewis/blackdoc + rev: v0.3.8 + hooks: + - id: blackdoc + additional_dependencies: [ 'black==23.3.0' ] + - repo: https://github.com/adrienverge/yamllint.git + rev: v1.32.0 + hooks: + - id: yamllint + args: ['--config-file', '.yamllint.yaml'] + - repo: https://github.com/mgedmin/check-manifest + rev: "0.49" + hooks: + - id: check-manifest + - repo: meta + hooks: + - id: check-hooks-apply + - id: check-useless-excludes + +ci: + autofix_commit_msg: | + [pre-commit.ci] auto fixes from pre-commit.com hooks + + for more information, see https://pre-commit.ci + autofix_prs: true + autoupdate_branch: '' + autoupdate_commit_msg: '[pre-commit.ci] pre-commit autoupdate' + autoupdate_schedule: weekly + skip: [] + submodules: false diff --git a/.readthedocs.yml b/.readthedocs.yml new file mode 100644 index 00000000..e0dc1642 --- /dev/null +++ b/.readthedocs.yml @@ -0,0 +1,26 @@ +# .readthedocs.yml +# Read the Docs configuration file +# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details + +version: 2 + +sphinx: + configuration: docs/conf.py + # fail_on_warning might generate hard to fix error, in this case it can be + # disabled but this also means those errors will fail silently, choose wisely. + fail_on_warning: true + +build: + os: ubuntu-22.04 + tools: + python: "mambaforge-4.10" + +conda: + environment: environment-docs.yml + +python: + install: + - method: pip + path: . + extra_requirements: + - dev diff --git a/.yamllint.yaml b/.yamllint.yaml new file mode 100644 index 00000000..2f3b4a3d --- /dev/null +++ b/.yamllint.yaml @@ -0,0 +1,8 @@ +--- + +rules: + document-start: disable + line-length: + max: 120 + level: warning + truthy: disable diff --git a/.zenodo.json b/.zenodo.json new file mode 100644 index 00000000..1150026f --- /dev/null +++ b/.zenodo.json @@ -0,0 +1,22 @@ +{ + "title": "xHydro", + "creators": [ + { + "name": "Fortier Filion, Thomas-Charles" + }, + { + "name": "Smith, Trevor James", + "affiliation": "Ouranos, MontrΓ©al, QuΓ©bec, Canada", + "orcid": "0000-0001-5393-8359" + } + ], + "keywords": [ + "hydrology", + "xarray" + ], + "license": "Apache-2.0", + "language": "eng", + "communities": [], + "upload_type": "software", + "access_right": "open" +} diff --git a/AUTHORS.rst b/AUTHORS.rst index 959720e5..68dec349 100644 --- a/AUTHORS.rst +++ b/AUTHORS.rst @@ -5,7 +5,12 @@ Credits Development Lead ---------------- -* Thomas-Charles Fortier Filion +* Thomas-Charles Fortier Filion `@TC-FF `_ + +Co-Developers +------------- + +* Trevor James Smith `@Zeitsperre `_ Contributors ------------ diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index 7423e59f..1e2a220b 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -15,7 +15,7 @@ Types of Contributions Report Bugs ~~~~~~~~~~~ -Report bugs at https://github.com/TC-FF/xhydro/issues. +Report bugs at https://github.com/hydrologie/xhydro/issues. If you are reporting a bug, please include: @@ -45,7 +45,7 @@ articles, and such. Submit Feedback ~~~~~~~~~~~~~~~ -The best way to send feedback is to file an issue at https://github.com/TC-FF/xhydro/issues. +The best way to send feedback is to file an issue at https://github.com/hydrologie/xhydro/issues. If you are proposing a feature: @@ -68,22 +68,32 @@ Ready to contribute? Here's how to set up `xhydro` for local development. $ mkvirtualenv xhydro $ cd xhydro/ - $ python setup.py develop + $ pip install -e . -4. Create a branch for local development:: +4. To ensure a consistent style, please install the pre-commit hooks to your repo:: + + $ pre-commit install + + Special style and formatting checks will be run when you commit your changes. You + can always run the hooks on their own with: + + $ pre-commit run -a + +5. Create a branch for local development:: $ git checkout -b name-of-your-bugfix-or-feature Now you can make your changes locally. -5. When you're done making changes, check that your changes pass flake8 and the +6. When you're done making changes, check that your changes pass flake8, black, and the tests, including testing other Python versions with tox:: $ flake8 xhydro tests + $ black --check xhydro tests $ python setup.py test or pytest $ tox - To get flake8 and tox, just pip install them into your virtualenv. + To get flake8, black, and tox, just pip install them into your virtualenv. 6. Commit your changes and push your branch to GitHub:: @@ -91,6 +101,13 @@ Ready to contribute? Here's how to set up `xhydro` for local development. $ git commit -m "Your detailed description of your changes." $ git push origin name-of-your-bugfix-or-feature +7. If you are editing the docs, compile and open them with:: + + $ make docs + # or to simply generate the html + $ cd docs/ + $ make html + 7. Submit a pull request through the GitHub website. Pull Request Guidelines @@ -102,9 +119,7 @@ Before you submit a pull request, check that it meets these guidelines: 2. If the pull request adds functionality, the docs should be updated. Put your new functionality into a function with a docstring, and add the feature to the list in README.rst. -3. The pull request should work for Python 3.5, 3.6, 3.7 and 3.8, and for PyPy. Check - https://travis-ci.com/TC-FF/xhydro/pull_requests - and make sure that the tests pass for all supported Python versions. +3. The pull request should work for Python 3.9, 3.10, and 3.11. Check that the tests pass for all supported Python versions. Tips ---- @@ -114,15 +129,85 @@ To run a subset of tests:: $ pytest tests.test_xhydro -Deploying ---------- +Versioning/Tagging +------------------ A reminder for the maintainers on how to deploy. Make sure all your changes are committed (including an entry in HISTORY.rst). Then run:: -$ bump2version patch # possible: major / minor / patch +$ bumpversion patch # possible: major / minor / patch $ git push $ git push --tags -Travis will then deploy to PyPI if tests pass. +Packaging +--------- + +When a new version has been minted (features have been successfully integrated test coverage and stability is adequate), +maintainers should update the pip-installable package (wheel and source release) on PyPI as well as the binary on conda-forge. + +The simple approach +~~~~~~~~~~~~~~~~~~~ + +The simplest approach to packaging for general support (pip wheels) requires the following packages installed: + * build + * setuptools + * twine + * wheel + +From the command line on your Linux distribution, simply run the following from the clone's main dev branch:: + + # To build the packages (sources and wheel) + $ python -m build --sdist --wheel + + # To upload to PyPI + $ twine upload dist/* + +The new version based off of the version checked out will now be available via `pip` (`$ pip install xhydro`). + +Releasing on conda-forge +~~~~~~~~~~~~~~~~~~~~~~~~ + +Initial Release +^^^^^^^^^^^^^^^ + +In order to prepare an initial release on conda-forge, we *strongly* suggest consulting the following links: + * https://conda-forge.org/docs/maintainer/adding_pkgs.html + * https://github.com/conda-forge/staged-recipes + +Before updating the main conda-forge recipe, we echo the conda-forge documentation and *strongly* suggest performing the following checks: + * Ensure that dependencies and dependency versions correspond with those of the tagged version, with open or pinned versions for the `host` requirements. + * If possible, configure tests within the conda-forge build CI (e.g. `imports: xhydro`, `commands: pytest xhydro`) + +Subsequent releases +^^^^^^^^^^^^^^^^^^^ + +If the conda-forge feedstock recipe is built from PyPI, then when a new release is published on PyPI, `regro-cf-autotick-bot` will open Pull Requests automatically on the conda-forge feedstock. +It is up to the conda-forge feedstock maintainers to verify that the package is building properly before merging the Pull Request to the main branch. + +Building sources for wide support with `manylinux` image +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. warning:: + This section is for building source files that link to or provide links to C/C++ dependencies. + It is not necessary to perform the following when building pure Python packages. + +In order to do ensure best compatibility across architectures, we suggest building wheels using the `PyPA`'s `manylinux` +docker images (at time of writing, we endorse using `manylinux_2_24_x86_64`). + +With `docker` installed and running, begin by pulling the image:: + + $ sudo docker pull quay.io/pypa/manylinux_2_24_x86_64 + +From the xhydro source folder we can enter into the docker container, providing access to the `xhydro` source files by linking them to the running image:: + + $ sudo docker run --rm -ti -v $(pwd):/xhydro -w /xhydro quay.io/pypa/manylinux_2_24_x86_64 bash + +Finally, to build the wheel, we run it against the provided Python3.8 binary:: + + $ /opt/python/cp38-cp38m/bin/python setup.py sdist bdist_wheel + +This will then place two files in `xhydro/dist/` ("xhydro-1.2.3-py3-none-any.whl" and "xhydro-1.2.3.tar.gz"). +We can now leave our docker container (`$ exit`) and continue with uploading the files to PyPI:: + + $ twine upload dist/* diff --git a/CHANGES.rst b/HISTORY.rst similarity index 100% rename from CHANGES.rst rename to HISTORY.rst diff --git a/LICENSE b/LICENSE index e2b8b29f..2b3b5ab0 100644 --- a/LICENSE +++ b/LICENSE @@ -13,4 +13,3 @@ distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. - diff --git a/MANIFEST.in b/MANIFEST.in index 965b2dda..35ca6d1c 100644 --- a/MANIFEST.in +++ b/MANIFEST.in @@ -3,9 +3,22 @@ include CONTRIBUTING.rst include HISTORY.rst include LICENSE include README.rst +include requirements_dev.txt +include requirements_docs.txt +include .zenodo.json +recursive-include docs *.rst conf.py Makefile make.bat *.jpg *.png *.gif recursive-include tests * recursive-exclude * __pycache__ recursive-exclude * *.py[co] -recursive-include docs *.rst conf.py Makefile make.bat *.jpg *.png *.gif +exclude .coveralls.yml +exclude .cruft.json +exclude .editorconfig +exclude .pre-commit-config.yaml +exclude .readthedocs.yml +exclude .yamllint.yaml +exclude Makefile +exclude environment.yml +exclude environment-docs.yml +exclude tox.ini diff --git a/Makefile b/Makefile index f7cdb8c1..f43a6a24 100644 --- a/Makefile +++ b/Makefile @@ -35,6 +35,11 @@ clean-build: ## remove build artifacts find . -name '*.egg-info' -exec rm -fr {} + find . -name '*.egg' -exec rm -f {} + +clean-docs: ## remove docs artifacts + rm -f docs/apidoc/xhydro*.rst + rm -f docs/apidoc/modules.rst + $(MAKE) -C docs clean + clean-pyc: ## remove Python file artifacts find . -name '*.pyc' -exec rm -f {} + find . -name '*.pyo' -exec rm -f {} + @@ -49,6 +54,7 @@ clean-test: ## remove test and coverage artifacts lint/flake8: ## check style with flake8 flake8 xhydro tests + lint/black: ## check style with black black --check xhydro tests @@ -66,23 +72,25 @@ coverage: ## check code coverage quickly with the default Python coverage html $(BROWSER) htmlcov/index.html -docs: ## generate Sphinx HTML documentation, including API docs - rm -f docs/xhydro.rst - rm -f docs/modules.rst - sphinx-apidoc -o docs/ xhydro - $(MAKE) -C docs clean +autodoc: clean-docs ## create sphinx-apidoc files: + sphinx-apidoc -o docs/apidoc --private --module-first xhydro + +linkcheck: autodoc ## run checks over all external links found throughout the documentation + $(MAKE) -C docs linkcheck + +docs: autodoc ## generate Sphinx HTML documentation, including API docs $(MAKE) -C docs html +ifndef READTHEDOCS $(BROWSER) docs/_build/html/index.html +endif servedocs: docs ## compile the docs watching for changes - watchmedo shell-command -p '*.rst' -c '$(MAKE) -C docs html' -R -D . - -release: dist ## package and upload a release + watchmedo shell-command -p '*.rst' -c '$(MAKE) -C docs html' -R -D .release: dist ## package and upload a release twine upload dist/* dist: clean ## builds source and wheel package - python setup.py sdist - python setup.py bdist_wheel + python -m build --sdist + python -m build --wheel ls -l dist install: clean ## install the package to the active Python's site-packages diff --git a/README.rst b/README.rst index 826f582f..a2ebe118 100644 --- a/README.rst +++ b/README.rst @@ -2,40 +2,45 @@ xHydro ====== +|pypi| |build| |docs| |license| -.. image:: https://img.shields.io/pypi/v/xhydro.svg - :target: https://pypi.python.org/pypi/xhydro - -.. image:: https://img.shields.io/travis/TC-FF/xhydro.svg - :target: https://travis-ci.com/TC-FF/xhydro +Hydrological analysis library built with xarray -.. image:: https://github.com/hydrologie/xhydro/actions/workflows/gh-pages.yml/badge.svg - :target: https://hydrologie.github.io/xhydro/ - :alt: Documentation Status +* Free software: Apache-2.0 +* Documentation: https://xhydro.readthedocs.io. -.. image:: https://pyup.io/repos/github/TC-FF/xhydro/shield.svg - :target: https://pyup.io/repos/github/TC-FF/xhydro/ - :alt: Updates +Features +-------- +* TODO +Credits +------- -Hydrology analysis build with xarray +This package was created with Cookiecutter_ and the `Ouranosinc/cookiecutter-pypackage`_ project template. +.. _Cookiecutter: https://github.com/cookiecutter/cookiecutter +.. _`Ouranosinc/cookiecutter-pypackage`: https://github.com/Ouranosinc/cookiecutter-pypackage -* Free software: Apache Software License 2.0 -* Documentation: https://hydrologie.github.io/xhydro/ +.. |pypi| image:: https://img.shields.io/pypi/v/xhydro.svg + :target: https://pypi.python.org/pypi/xhydro -Features --------- -* TODO +.. |build| image:: https://github.com/hydrologie/xhydro/workflows/xhydro/badge.svg + :target: https://github.com/hydrologie/xhydro + :alt: Build Status -Credits -------- +.. |docs| image:: https://img.shields.io/badge/Docs-GitHub.io-blue + :target: https://hydrologie.github.io/xhydro/ + :alt: Documentation -This package was created with Cookiecutter_ and the `audreyr/cookiecutter-pypackage`_ project template. +.. + .. |docs| image:: https://readthedocs.org/projects/xhydro/badge/?version=latest + :target: https://xhydro.readthedocs.io/en/latest/?version=latest + :alt: Documentation Status -.. _Cookiecutter: https://github.com/audreyr/cookiecutter -.. _`audreyr/cookiecutter-pypackage`: https://github.com/audreyr/cookiecutter-pypackage +.. |license| image:: https://img.shields.io/pypi/l/xhydro + :target: https://github.com/hydrologie/xhydro/blob/main/LICENSE + :alt: License diff --git a/docs/changes.rst b/docs/changes.rst deleted file mode 100644 index d9e113ec..00000000 --- a/docs/changes.rst +++ /dev/null @@ -1 +0,0 @@ -.. include:: ../CHANGES.rst diff --git a/docs/conf.py b/docs/conf.py old mode 100644 new mode 100755 index 694cf65b..fda34a83 --- a/docs/conf.py +++ b/docs/conf.py @@ -31,7 +31,28 @@ # 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.viewcode', 'nbsphinx'] +extensions = [ + 'sphinx.ext.autodoc', + 'sphinx.ext.autosectionlabel', + 'sphinx.ext.viewcode', + 'sphinx.ext.todo', + 'sphinx_codeautolink', + 'sphinx_copybutton', + "nbsphinx" +] + +autosectionlabel_prefix_document = True +autosectionlabel_maxdepth = 2 + +# To ensure that underlined fields (e.g. `_field`) are shown in the docs. +autodoc_default_options = { + "members": True, + "undoc-members": True, + "private-members": False, + "special-members": False, +} + +# Generate documentation from Jupyter notebooks. nbsphinx_execute = 'always' # Add any paths that contain templates here, relative to this directory. @@ -41,7 +62,7 @@ # You can specify multiple suffix as a list of string: # # source_suffix = ['.rst', '.md'] -source_suffix = '.rst' +source_suffix = ['.rst'] # The master toctree document. master_doc = 'index' @@ -65,7 +86,7 @@ # # This is also used if you do content translation via gettext catalogs. # Usually you set "language" from the command line for these cases. -language = None +language = "en" # List of patterns, relative to source directory, that match files and # directories to ignore when looking for source files. @@ -155,9 +176,6 @@ 'xHydro Documentation', author, 'xhydro', - 'Hydrological analysis build with xarray.', - 'Miscellaneous'), + 'Hydrological analysis library built with xarray.', + 'hydrology'), ] - - - diff --git a/docs/history.rst b/docs/history.rst new file mode 100644 index 00000000..25064996 --- /dev/null +++ b/docs/history.rst @@ -0,0 +1 @@ +.. include:: ../HISTORY.rst diff --git a/docs/index.rst b/docs/index.rst index 830a706e..4d4f1fb4 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,5 +1,5 @@ Welcome to xHydro's documentation! -====================================== +================================== .. toctree:: :maxdepth: 2 diff --git a/docs/installation.rst b/docs/installation.rst index 56a1d0b5..d499bd94 100644 --- a/docs/installation.rst +++ b/docs/installation.rst @@ -1,5 +1,3 @@ -.. highlight:: shell - ============ Installation ============ @@ -32,13 +30,13 @@ You can either clone the public repository: .. code-block:: console - $ git clone git://github.com/TC-FF/xhydro + $ git clone git@github.com:hydrologie/xhydro Or download the `tarball`_: .. code-block:: console - $ curl -OJL https://github.com/TC-FF/xhydro/tarball/master + $ curl -OJL https://github.com/hydrologie/xhydro/tarball/master Once you have a copy of the source, you can install it with: @@ -47,5 +45,5 @@ Once you have a copy of the source, you can install it with: $ python setup.py install -.. _Github repo: https://github.com/TC-FF/xhydro -.. _tarball: https://github.com/TC-FF/xhydro/tarball/master +.. _Github repo: https://github.com/hydrologie/xhydro +.. _tarball: https://github.com/hydrologie/xhydro/tarball/master diff --git a/environment-docs.yml b/environment-docs.yml new file mode 100644 index 00000000..32509da7 --- /dev/null +++ b/environment-docs.yml @@ -0,0 +1,13 @@ +name: xhydro +channels: + - conda-forge + - defaults +dependencies: + - sphinx + - furo + - mock + - pandoc + - sphinx-autoapi + - sphinx-codeautolink + - sphinx-copybutton + - sphinxcontrib-napoleon diff --git a/environment.yml b/environment.yml index 201fd0d7..25affbc6 100644 --- a/environment.yml +++ b/environment.yml @@ -1,28 +1,37 @@ name: xhydro channels: - - conda-forge + - conda-forge dependencies: - - python=3.10 - - IPyKernel - - xarray - - dask - - netCDF4 - - bottleneck - - s3fs - - zarr - - cartopy - - geoviews - - rioxarray - - matplotlib - - intake - - geopandas - - hvplot - - intake-xarray=0.6.1 - - intake-geopandas - - nbsphinx - - sphinx - - xclim - - pymannkendall - - pip: - - sphinx-pangeo-theme - - furo \ No newline at end of file + - python >=3.10,<3.11 + - IPyKernel + - bottleneck >=1.3.1 + - cartopy + - cftime >=1.4.1 + - cf_xarray >=0.6.1 + - dask >=2.6 + - furo + - geopandas + - geoviews + - h5netcdf + - hvplot + - intake + - intake-geopandas + - intake-xarray >=0.6.1 + - jsonpickle + - matplotlib-base + - nbsphinx + - netCDF4 + - numba + - numpy >=1.16.0 + - pymannkendall + - rioxarray + - s3fs >=2022.7.0 + - scipy >=1.2 + - sphinx + - sphinx-autoapi + - sphinx-codeautolink + - sphinx-copybutton + - sphinxcontrib-napoleon + - xarray >=0.17.0 + - xclim >=0.43.0 + - zarr >=2.11.1 diff --git a/requirements_dev.txt b/requirements_dev.txt index ebb3f1d1..86782b21 100644 --- a/requirements_dev.txt +++ b/requirements_dev.txt @@ -1,12 +1,16 @@ -pip==19.2.3 -bump2version==0.5.11 -wheel==0.33.6 -watchdog==0.9.0 -flake8==3.7.8 -tox==3.14.0 -coverage==4.5.4 -Sphinx==1.8.5 -twine==1.14.0 - -pytest==6.2.4 -black==21.7b0 +Click +black>=23.3.0 +build +bump2version +coverage +coveralls +flake8 +isort>=5.12.0 +pip +pre-commit +pytest +pytest-cov +tox +twine +watchdog +wheel diff --git a/requirements_docs.txt b/requirements_docs.txt new file mode 100644 index 00000000..4eb3499c --- /dev/null +++ b/requirements_docs.txt @@ -0,0 +1,10 @@ +furo +ipykernel +ipython +jupyter_client +nbsphinx +pandoc +sphinx +sphinx-click +sphinx-codeautolink +sphinx-copybutton diff --git a/setup.cfg b/setup.cfg index 852c3ce3..e2a40b9d 100644 --- a/setup.cfg +++ b/setup.cfg @@ -4,18 +4,74 @@ commit = True tag = True [bumpversion:file:setup.py] -search = version='{current_version}' -replace = version='{new_version}' +search = version="{current_version}" +replace = version="{new_version}" [bumpversion:file:xhydro/__init__.py] -search = __version__ = '{current_version}' -replace = __version__ = '{new_version}' +search = __version__ = "{current_version}" +replace = __version__ = "{new_version}" -[bdist_wheel] -universal = 1 +[bumpversion:file:tests/test_xhydro.py] +search = __version__ = "{current_version}" +replace = __version__ = "{new_version}" -[flake8] -exclude = docs +[bumpversion:file:.cruft.json] +search = "version": "{current_version}", +replace = "version": "{new_version}", + +[aliases] +test = pytest [tool:pytest] collect_ignore = ['setup.py'] +addopts = + --verbose +filterwarnings = + ignore::UserWarning + +[flake8] +exclude = + .git, + docs, + build, + .eggs, + docs/conf.py, +max-line-length = 88 +max-complexity = 12 +ignore = + C901 + E203 + E231 + E266 + E501 + F401 + F403 + W503 + W504 +per-file-ignores = + tests/*:E402 +rst-roles = + mod, + py:attr, + py:attribute, + py:class, + py:const, + py:data, + py:func, + py:meth, + py:mod, + py:obj, + py:ref, + ref + +[coverage:run] +relative_files = True +omit = */tests/*.py + +[isort] +profile = black +py_version = 39 + +[pydocstyle] +convention = numpy +match = ((?!test_|conf).)*\.py diff --git a/setup.py b/setup.py index a91f7988..b07cb531 100644 --- a/setup.py +++ b/setup.py @@ -2,18 +2,17 @@ """The setup script.""" -from setuptools import setup, find_packages +from setuptools import find_packages, setup -with open('README.rst') as readme_file: +with open("README.rst") as readme_file: readme = readme_file.read() -with open('CHANGES.rst') as history_file: +with open("HISTORY.rst") as history_file: history = history_file.read() requirements = [ "bottleneck>=1.3.1", "cartopy", - "cftime", "cf-xarray>=0.6.1", "cftime>=1.4.1", "dask[array]>=2.6", @@ -22,45 +21,63 @@ "intake-xarray>=0.6.1", "jsonpickle", "numba", - "numpy>=1.16", + "numpy>=1.16.0", "pandas>=0.23", "pint>=0.10", "pyarrow", "pyyaml", "s3fs>=2022.7.0", "scipy>=1.2", - "xarray>=0.17", - "xclim>=0.37", - "zarr>=2.11.1" - ] + "xarray>=0.17.0", + "xclim>=0.43.0", + "zarr>=2.11.1", +] -test_requirements = ['pytest>=3', ] +test_requirements = ["pytest>=3"] + +docs_requirements = [ + dependency for dependency in open("requirements_docs.txt").readlines() +] + +dev_requirements = [ + dependency for dependency in open("requirements_dev.txt").readlines() +] setup( author="Thomas-Charles Fortier Filion", - author_email='tcff_hydro@outlook.com', - python_requires='>=3.8', + author_email="tcff_hydro@outlook.com", + python_requires=">=3.9", classifiers=[ - 'Development Status :: 2 - Pre-Alpha', - 'Intended Audience :: Developers', - 'License :: OSI Approved :: Apache Software License', - 'Natural Language :: English', - 'Programming Language :: Python :: 3', - 'Programming Language :: Python :: 3.8', - 'Programming Language :: Python :: 3.9', - 'Programming Language :: Python :: 3.10', + "Development Status :: 2 - Pre-Alpha", + "Intended Audience :: Developers", + "License :: OSI Approved :: Apache Software License", + "Natural Language :: English", + "Programming Language :: Python :: 3", + "Programming Language :: Python :: 3.9", + "Programming Language :: Python :: 3.10", + "Programming Language :: Python :: 3.11", ], - description="Hydrology analysis build with xarray", + description="Hydrological analysis library built with xarray", + entry_points={ + "console_scripts": [ + "xhydro=xhydro.cli:main", + ], + }, install_requires=requirements, license="Apache Software License 2.0", - long_description=readme + '\n\n' + history, + long_description=readme + "\n\n" + history, + long_description_content_type="text/x-rst", include_package_data=True, - keywords='xhydro', - name='xhydro', - packages=find_packages(include=['xhydro', 'xhydro.*']), - test_suite='tests', + keywords="xhydro", + name="xhydro", + packages=find_packages(include=["xhydro", "xhydro.*"]), + test_suite="tests", tests_require=test_requirements, - url='https://github.com/TC-FF/xhydro', - version='0.1.2', + extras_require={ + "docs": docs_requirements, + "dev": dev_requirements, + }, + url="https://github.com/TC-FF/xhydro", + version="0.1.2", zip_safe=False, ) diff --git a/tests/test_xhydro.py b/tests/test_xhydro.py index 13b8e0b3..e58c13e8 100644 --- a/tests/test_xhydro.py +++ b/tests/test_xhydro.py @@ -2,8 +2,9 @@ """Tests for `xhydro` package.""" -import pytest +from pathlib import Path +import pytest from xhydro import xhydro @@ -12,13 +13,25 @@ def response(): """Sample pytest fixture. - See more at: http://doc.pytest.org/en/latest/fixture.html + See more at: https://doc.pytest.org/en/latest/explanation/fixtures.html """ # import requests # return requests.get('https://github.com/audreyr/cookiecutter-pypackage') + pass def test_content(response): """Sample pytest test function with the pytest fixture as an argument.""" # from bs4 import BeautifulSoup # assert 'GitHub' in BeautifulSoup(response.content).title.string + pass + + +def test_imports(): + metadata = Path(xhydro.__file__).resolve().parent.joinpath("__init__.py") + + with open(metadata) as f: + contents = f.read() + assert '__author__ = """Thomas-Charles Fortier Filion"""' in contents + assert '__email__ = "tcff_hydro@outlook.com"' in contents + assert '__version__ = "0.1.2"' in contents diff --git a/tox.ini b/tox.ini index 8c26ace4..a844459f 100644 --- a/tox.ini +++ b/tox.ini @@ -1,26 +1,48 @@ [tox] -envlist = py36, py37, py38, flake8 +min_version = 4.0 +envlist = + black + py{39,310,311} + docs + coveralls +requires = + pip >= 21.0 +opts = + --verbose -[travis] -python = - 3.8: py38 - 3.7: py37 - 3.6: py36 +[testenv:black] +skip_install = True +deps = + flake8 + black +commands = + make lint +allowlist_externals = + make -[testenv:flake8] -basepython = python -deps = flake8 -commands = flake8 xhydro tests +[testenv:docs] +extras = + docs +commands = + make --directory=docs clean html +allowlist_externals = + make [testenv] setenv = + PYTEST_ADDOPTS = "--color=yes" PYTHONPATH = {toxinidir} +passenv = + GITHUB_* +extras = + dev +download = True +install_command = python -m pip install --no-user {opts} {packages} deps = - -r{toxinidir}/requirements_dev.txt ; If you want to make tox run the tests with the same versions, create a ; requirements.txt with the pinned versions and uncomment the following line: ; -r{toxinidir}/requirements.txt commands = - pip install -U pip - pytest --basetemp={envtmpdir} - + pytest --cov xhydro + # Coveralls requires access to a repo token set in .coveralls.yml in order to report stats + coveralls: - coveralls diff --git a/xhydro/__init__.py b/xhydro/__init__.py index 7b023a7c..399b3aa6 100644 --- a/xhydro/__init__.py +++ b/xhydro/__init__.py @@ -1,5 +1,5 @@ """Top-level package for xHydro.""" __author__ = """Thomas-Charles Fortier Filion""" -__email__ = 'tcff_hydro@outlook.com' -__version__ = '0.1.2' +__email__ = "tcff_hydro@outlook.com" +__version__ = "0.1.2"