diff --git a/.binder/postBuild b/.binder/postBuild index f8b88ac..84313c3 100644 --- a/.binder/postBuild +++ b/.binder/postBuild @@ -1,20 +1,20 @@ # pip install main pip install --no-deps . -# Note: This produces build and pyiron_module_template.egg-info directories +# Note: This produces build and pyiron_snippets.egg-info directories # clean up if [ -d "notebooks" ]; then mv notebooks/* . fi -if [ -d "${HOME}/pyiron_module_template" ]; then +if [ -d "${HOME}/pyiron_snippets" ]; then rm -r ${HOME}/.binder \ ${HOME}/.ci_support \ ${HOME}/.github \ ${HOME}/build \ ${HOME}/docs \ ${HOME}/notebooks \ - ${HOME}/pyiron_module_template \ - ${HOME}/pyiron_module_template.egg-info \ + ${HOME}/pyiron_snippets \ + ${HOME}/pyiron_snippets.egg-info \ ${HOME}/tests \ ${HOME}/.gitattributes \ ${HOME}/.gitignore \ diff --git a/.coveragerc b/.coveragerc index 0176c43..c20580f 100644 --- a/.coveragerc +++ b/.coveragerc @@ -1,5 +1,5 @@ # .coveragerc to control coverage.py [run] -source = pyiron_module_template -omit = pyiron_module_template/_version.py +source = pyiron_snippets +omit = pyiron_snippets/_version.py concurrency = multiprocessing \ No newline at end of file diff --git a/.gitattributes b/.gitattributes index 84b63df..07aa519 100644 --- a/.gitattributes +++ b/.gitattributes @@ -1 +1 @@ -pyiron_module_template/_version.py export-subst +pyiron_snippets/_version.py export-subst diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md index 3a29cab..b2c29e2 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.md +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -1,6 +1,6 @@ --- name: Bug report -about: Create a bug report to help us eliminate issues and improve pyiron_module_template +about: Create a bug report to help us eliminate issues and improve pyiron_snippets title: '' labels: bug assignees: '' diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md index f96aa7b..79e8109 100644 --- a/.github/ISSUE_TEMPLATE/feature_request.md +++ b/.github/ISSUE_TEMPLATE/feature_request.md @@ -1,6 +1,6 @@ --- name: Feature request -about: Make a suggestion for a new feature or a change to pyiron_module_template +about: Make a suggestion for a new feature or a change to pyiron_snippets title: '' labels: enhancement assignees: '' @@ -13,7 +13,7 @@ assignees: '' **Detailed Description** - + **Further Information, Files, and Links** diff --git a/docs/README.md b/docs/README.md index 9fb235a..77f6253 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,106 +1,5 @@ -# pyiron_module_template +# pyiron_snippets -## Overview +This is a collection of independent python snippets used in the pyiron project, but hopefully useful elsewhere too. -This repository is a template for new pyiron modules similar to the existing modules of the -pyiron framework, e.g. -[pyiron_workflow](https://github.com/pyiron/pyiron_workflow), -[pyiron_ontology](https://github.com/pyiron/pyiron_ontology), -etc. - -Within this repository, the new module is called `pyiron_module_template` which should be renamed to `pyiron_IntendedModuleName`. -This can be easily achieved by modifying and running the update_module_name.sh script. - -The licence is free to choose, but as a default the BSD3 licence packed here. - -## Continuous Integration - -We collect all files relevant for the continuous integration (CI) pipelines in `.ci_support`, -while the actual CI workflows are handled by GitHub and stored in `.github`. -If you are cloning this template *inside* the pyiron GitHub organization, the full CI should work out-of-the-box by calling reusable workflows from [pyiron/actions](github.com/pyiron/actions) and inheriting organization-wide secrets. -Otherwise, you will either need to modify the CI workflow files, or give your repository the following secrets: -- `DEPENDABOT_WORKFLOW_TOKEN` (GitHub token for an account that has permissions to your repository -- needs to differ from the default `github_token` already available though! In pyiron we have a special [@pyiron_runner account](https://github.com/pyiron-runner) for this purpose.) -- `PYPI_PASSWORD` (Token generated on PyPi to give access to your account there) -- `CODACY_PROJECT_TOKEN` (Token generated on Codacy to give access to your account there) - -The default CI setup from [pyiron/actions](github.com/pyiron/actions) makes some assumptions about your directory structure. -The most important one is that your environment should be specified in `.ci_support/environment.yml`. -There is a base environment there already, giving dependence on `pyiron_base`. -The CI will automatically keep environment files read by readthedocs (which will look at `.readthedocs.yml`) and MyBinder (which looks in `.binder`) up-to-date based on this environment file. - -In case you need extra environment files for some setups, you can modify the workflows in `.github/workflows`, which accept input variables for the docs, tests, and notebooks environments. -For example, it's typically good to not make your project depend on the `lammps` package, since this is not available for windows. -However, you might want to give some demo notebooks that run on MyBinder (a linux environment) and use LAMMPS calculations. -In this case, you could add a new file `.ci_support/environment-notebooks.yml`, and then edit `.github/workflows/push-pull.yml` so that instead of reading - -```yaml -jobs: - pyiron: - uses: pyiron/actions/.github/workflows/push-pull.yml@actions-1.1.0b - secrets: inherit - # All the environment files variables point to .ci_support/environment.yml by default -``` - -It instead reads - -```yaml -jobs: - pyiron: - uses: pyiron/actions/.github/workflows/push-pull.yml@actions-1.1.0b - secrets: inherit - with: - notebooks-env-files: .ci_support/environment.yml .ci_support/environment-notebooks.yml -``` - -Where `.ci_support/environment-notebooks.yml` looks like: - -```yaml -channels: - - conda-forge -dependencies: - - lammps -``` - -### Label-based CI - -Some CI triggers when labels get applied to a PR. -In a new repository, you will need to define these labels: -- `format_black`: Runs black analyis and creates a bot-generated commit to fix any format violations -- `run_CodeQL`: Runs the external CodeQL analysis (expensive, only do at the end) -- `run_coverage`: Run all the tests in `tests` and use coveralls to generate a coverage report (also expensive, only run near the end of your PR) - -## Documentation - -You should modify this README to reflect the purpose of your new package. -You can look at the other pyiron modules to get a hint for what sort of information to include, and how to link badges at the head of your README file. - -At a minimum, we suggest creating a meaningful example notebook in the `notebooks/` directory and creating a MyBinder badge so that people can quickly and easily explore your work. - -You can also edit the docs for your package by modifying `docs/index.rst`. -By default, this README is used as the landing page, and a simple API section is automatically generated. - -## Tests - -There is space for "benchmark", "integration", and "unit" tests in the `tests/` directory, with dummy tests for each. -These are run by the default CI, so modify them to suit your needs. - -Additionally, the standard CI will attempt to execute all notebooks in the `notebooks/` directory. -See [`pyiron/actions`](https://github.com/pyiron/actions) and the reusable workflows there to learn about modifying the environment for the CI, e.g. to use a different env for notebook runs than for the tests in `tests/`. - -Finally, `tests/integration/test_readme.py` shows how example code in the documentation gets tested against its claimed output. -E.g. if you change this: - -```python ->>> print(2 + 2) -4 - -``` - -To read `5` instead, those tests should fail. - -## Publishing your package - -If you are inside the pyiron organization or have your own `PYPI_PASSWORD` secret configured, your package will be published on PyPI automatically when you make a new "release" on GitHub -- *as long as* that tag matches the pattern specified in `setup.cfg`; by default any tag that `pyiron_module_template-`, where `pyiron_module_template` is replaced with the name of your module. We recommend using semantic versioning so that your first release looks like `pyiron_module_template-0.0.1`. - -Releasing your package on Conda-Forge is slightly more involved, but not too hard (at least for pure python packages). -See [conda-forge/staged-recipes](https://github.com/conda-forge/staged-recipes) for how to publish it there. +To qualify for inclusion, a snippet must not have any dependencies outside the python standard library, and should fit reasonably inside a single file. diff --git a/docs/conf.py b/docs/conf.py index 3a5bca9..0da0f1b 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -66,7 +66,7 @@ master_doc = 'index' # General information about the project. -project = u'pyiron_module_template' +project = u'pyiron_snippets' copyright = u'2021, Max-Planck-Institut für Eisenforschung GmbH - Computational Materials Design (CM) Department ' \ u'All rights reserved' @@ -244,7 +244,7 @@ # (source start file, target name, title, # author, documentclass [howto, manual, or own class]). latex_documents = [ - ('index', 'pyiron_module_template.tex', u'pyiron_module_template Documentation', + ('index', 'pyiron_snippets.tex', u'pyiron_snippets Documentation', u'Max-Planck-Institut für Eisenforschung GmbH - Computational Materials Design (CM) Department', 'manual'), ] @@ -275,8 +275,8 @@ # (source start file, name, description, authors, manual section). man_pages = [ ('index', - 'pyiron_module_template', - u'pyiron_module_template Documentation', + 'pyiron_snippets', + u'pyiron_snippets Documentation', [u'Max-Planck-Institut für Eisenforschung GmbH - Computational Materials Design (CM) Department'], 1) ] @@ -291,10 +291,10 @@ # dir menu entry, description, category) texinfo_documents = [ ('index', - 'pyiron_module_template', - u'pyiron_module_template Documentation', + 'pyiron_snippets', + u'pyiron_snippets Documentation', u'Max-Planck-Institut für Eisenforschung GmbH - Computational Materials Design (CM) Department', - 'pyiron_module_template', + 'pyiron_snippets', 'One line description of project.', 'Miscellaneous'), ] @@ -311,7 +311,7 @@ # If true, do not generate a @detailmenu in the "Top" node's menu. # texinfo_no_detailmenu = False -main(['-e', '-o', 'apidoc', '../pyiron_module_template', '--force']) +main(['-e', '-o', 'apidoc', '../pyiron_snippets', '--force']) curdir = os.path.dirname(os.path.abspath(__file__)) if os.path.exists(os.path.join(curdir, 'source/notebooks')): diff --git a/docs/index.rst b/docs/index.rst index 0b225aa..5e96bd0 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,4 +1,4 @@ -.. pyiron_module_template documentation master file +.. pyiron_snippets documentation master file .. _index: diff --git a/notebooks/example.ipynb b/notebooks/example.ipynb index dc2f1b8..02892d4 100644 --- a/notebooks/example.ipynb +++ b/notebooks/example.ipynb @@ -19,8 +19,8 @@ "metadata": {}, "outputs": [], "source": [ - "import pyiron_module_template\n", - "print(pyiron_module_template.__version__)" + "import pyiron_snippets\n", + "print(pyiron_snippets.__version__)" ] } ], diff --git a/pyiron_module_template/__init__.py b/pyiron_module_template/__init__.py deleted file mode 100644 index e69de29..0000000 diff --git a/pyiron_snippets/__init__.py b/pyiron_snippets/__init__.py new file mode 100644 index 0000000..ecd3379 --- /dev/null +++ b/pyiron_snippets/__init__.py @@ -0,0 +1,3 @@ + +from . import _version +__version__ = _version.get_versions()['version'] diff --git a/pyiron_snippets/_version.py b/pyiron_snippets/_version.py new file mode 100644 index 0000000..5bb3058 --- /dev/null +++ b/pyiron_snippets/_version.py @@ -0,0 +1,683 @@ + +# This file helps to compute a version number in source trees obtained from +# git-archive tarball (such as those provided by githubs download-from-tag +# feature). Distribution tarballs (built by setup.py sdist) and build +# directories (produced by setup.py build) will contain a much shorter file +# that just contains the computed version number. + +# This file is released into the public domain. +# Generated by versioneer-0.29 +# https://github.com/python-versioneer/python-versioneer + +"""Git implementation of _version.py.""" + +import errno +import os +import re +import subprocess +import sys +from typing import Any, Callable, Dict, List, Optional, Tuple +import functools + + +def get_keywords() -> Dict[str, str]: + """Get the keywords needed to look up the version information.""" + # these strings will be replaced by git during git-archive. + # setup.py/versioneer.py will grep for the variable names, so they must + # each be defined on a line of their own. _version.py will just call + # get_keywords(). + git_refnames = "$Format:%d$" + git_full = "$Format:%H$" + git_date = "$Format:%ci$" + keywords = {"refnames": git_refnames, "full": git_full, "date": git_date} + return keywords + + +class VersioneerConfig: + """Container for Versioneer configuration parameters.""" + + VCS: str + style: str + tag_prefix: str + parentdir_prefix: str + versionfile_source: str + verbose: bool + + +def get_config() -> VersioneerConfig: + """Create, populate and return the VersioneerConfig() object.""" + # these strings are filled in when 'setup.py versioneer' creates + # _version.py + cfg = VersioneerConfig() + cfg.VCS = "git" + cfg.style = "pep440-pre" + cfg.tag_prefix = "pyiron_snippets-" + cfg.parentdir_prefix = "pyiron_snippets" + cfg.versionfile_source = "pyiron_snippets/_version.py" + cfg.verbose = False + return cfg + + +class NotThisMethod(Exception): + """Exception raised if a method is not valid for the current scenario.""" + + +LONG_VERSION_PY: Dict[str, str] = {} +HANDLERS: Dict[str, Dict[str, Callable]] = {} + + +def register_vcs_handler(vcs: str, method: str) -> Callable: # decorator + """Create decorator to mark a method as the handler of a VCS.""" + def decorate(f: Callable) -> Callable: + """Store f in HANDLERS[vcs][method].""" + if vcs not in HANDLERS: + HANDLERS[vcs] = {} + HANDLERS[vcs][method] = f + return f + return decorate + + +def run_command( + commands: List[str], + args: List[str], + cwd: Optional[str] = None, + verbose: bool = False, + hide_stderr: bool = False, + env: Optional[Dict[str, str]] = None, +) -> Tuple[Optional[str], Optional[int]]: + """Call the given command(s).""" + assert isinstance(commands, list) + process = None + + popen_kwargs: Dict[str, Any] = {} + if sys.platform == "win32": + # This hides the console window if pythonw.exe is used + startupinfo = subprocess.STARTUPINFO() + startupinfo.dwFlags |= subprocess.STARTF_USESHOWWINDOW + popen_kwargs["startupinfo"] = startupinfo + + for command in commands: + try: + dispcmd = str([command] + args) + # remember shell=False, so use git.cmd on windows, not just git + process = subprocess.Popen([command] + args, cwd=cwd, env=env, + stdout=subprocess.PIPE, + stderr=(subprocess.PIPE if hide_stderr + else None), **popen_kwargs) + break + except OSError as e: + if e.errno == errno.ENOENT: + continue + if verbose: + print("unable to run %s" % dispcmd) + print(e) + return None, None + else: + if verbose: + print("unable to find command, tried %s" % (commands,)) + return None, None + stdout = process.communicate()[0].strip().decode() + if process.returncode != 0: + if verbose: + print("unable to run %s (error)" % dispcmd) + print("stdout was %s" % stdout) + return None, process.returncode + return stdout, process.returncode + + +def versions_from_parentdir( + parentdir_prefix: str, + root: str, + verbose: bool, +) -> Dict[str, Any]: + """Try to determine the version from the parent directory name. + + Source tarballs conventionally unpack into a directory that includes both + the project name and a version string. We will also support searching up + two directory levels for an appropriately named parent directory + """ + rootdirs = [] + + for _ in range(3): + dirname = os.path.basename(root) + if dirname.startswith(parentdir_prefix): + return {"version": dirname[len(parentdir_prefix):], + "full-revisionid": None, + "dirty": False, "error": None, "date": None} + rootdirs.append(root) + root = os.path.dirname(root) # up a level + + if verbose: + print("Tried directories %s but none started with prefix %s" % + (str(rootdirs), parentdir_prefix)) + raise NotThisMethod("rootdir doesn't start with parentdir_prefix") + + +@register_vcs_handler("git", "get_keywords") +def git_get_keywords(versionfile_abs: str) -> Dict[str, str]: + """Extract version information from the given file.""" + # the code embedded in _version.py can just fetch the value of these + # keywords. When used from setup.py, we don't want to import _version.py, + # so we do it with a regexp instead. This function is not used from + # _version.py. + keywords: Dict[str, str] = {} + try: + with open(versionfile_abs, "r") as fobj: + for line in fobj: + if line.strip().startswith("git_refnames ="): + mo = re.search(r'=\s*"(.*)"', line) + if mo: + keywords["refnames"] = mo.group(1) + if line.strip().startswith("git_full ="): + mo = re.search(r'=\s*"(.*)"', line) + if mo: + keywords["full"] = mo.group(1) + if line.strip().startswith("git_date ="): + mo = re.search(r'=\s*"(.*)"', line) + if mo: + keywords["date"] = mo.group(1) + except OSError: + pass + return keywords + + +@register_vcs_handler("git", "keywords") +def git_versions_from_keywords( + keywords: Dict[str, str], + tag_prefix: str, + verbose: bool, +) -> Dict[str, Any]: + """Get version information from git keywords.""" + if "refnames" not in keywords: + raise NotThisMethod("Short version file found") + date = keywords.get("date") + if date is not None: + # Use only the last line. Previous lines may contain GPG signature + # information. + date = date.splitlines()[-1] + + # git-2.2.0 added "%cI", which expands to an ISO-8601 -compliant + # datestamp. However we prefer "%ci" (which expands to an "ISO-8601 + # -like" string, which we must then edit to make compliant), because + # it's been around since git-1.5.3, and it's too difficult to + # discover which version we're using, or to work around using an + # older one. + date = date.strip().replace(" ", "T", 1).replace(" ", "", 1) + refnames = keywords["refnames"].strip() + if refnames.startswith("$Format"): + if verbose: + print("keywords are unexpanded, not using") + raise NotThisMethod("unexpanded keywords, not a git-archive tarball") + refs = {r.strip() for r in refnames.strip("()").split(",")} + # starting in git-1.8.3, tags are listed as "tag: foo-1.0" instead of + # just "foo-1.0". If we see a "tag: " prefix, prefer those. + TAG = "tag: " + tags = {r[len(TAG):] for r in refs if r.startswith(TAG)} + if not tags: + # Either we're using git < 1.8.3, or there really are no tags. We use + # a heuristic: assume all version tags have a digit. The old git %d + # expansion behaves like git log --decorate=short and strips out the + # refs/heads/ and refs/tags/ prefixes that would let us distinguish + # between branches and tags. By ignoring refnames without digits, we + # filter out many common branch names like "release" and + # "stabilization", as well as "HEAD" and "master". + tags = {r for r in refs if re.search(r'\d', r)} + if verbose: + print("discarding '%s', no digits" % ",".join(refs - tags)) + if verbose: + print("likely tags: %s" % ",".join(sorted(tags))) + for ref in sorted(tags): + # sorting will prefer e.g. "2.0" over "2.0rc1" + if ref.startswith(tag_prefix): + r = ref[len(tag_prefix):] + # Filter out refs that exactly match prefix or that don't start + # with a number once the prefix is stripped (mostly a concern + # when prefix is '') + if not re.match(r'\d', r): + continue + if verbose: + print("picking %s" % r) + return {"version": r, + "full-revisionid": keywords["full"].strip(), + "dirty": False, "error": None, + "date": date} + # no suitable tags, so version is "0+unknown", but full hex is still there + if verbose: + print("no suitable tags, using unknown + full revision id") + return {"version": "0+unknown", + "full-revisionid": keywords["full"].strip(), + "dirty": False, "error": "no suitable tags", "date": None} + + +@register_vcs_handler("git", "pieces_from_vcs") +def git_pieces_from_vcs( + tag_prefix: str, + root: str, + verbose: bool, + runner: Callable = run_command +) -> Dict[str, Any]: + """Get version from 'git describe' in the root of the source tree. + + This only gets called if the git-archive 'subst' keywords were *not* + expanded, and _version.py hasn't already been rewritten with a short + version string, meaning we're inside a checked out source tree. + """ + GITS = ["git"] + if sys.platform == "win32": + GITS = ["git.cmd", "git.exe"] + + # GIT_DIR can interfere with correct operation of Versioneer. + # It may be intended to be passed to the Versioneer-versioned project, + # but that should not change where we get our version from. + env = os.environ.copy() + env.pop("GIT_DIR", None) + runner = functools.partial(runner, env=env) + + _, rc = runner(GITS, ["rev-parse", "--git-dir"], cwd=root, + hide_stderr=not verbose) + if rc != 0: + if verbose: + print("Directory %s not under git control" % root) + raise NotThisMethod("'git rev-parse --git-dir' returned error") + + # if there is a tag matching tag_prefix, this yields TAG-NUM-gHEX[-dirty] + # if there isn't one, this yields HEX[-dirty] (no NUM) + describe_out, rc = runner(GITS, [ + "describe", "--tags", "--dirty", "--always", "--long", + "--match", f"{tag_prefix}[[:digit:]]*" + ], cwd=root) + # --long was added in git-1.5.5 + if describe_out is None: + raise NotThisMethod("'git describe' failed") + describe_out = describe_out.strip() + full_out, rc = runner(GITS, ["rev-parse", "HEAD"], cwd=root) + if full_out is None: + raise NotThisMethod("'git rev-parse' failed") + full_out = full_out.strip() + + pieces: Dict[str, Any] = {} + pieces["long"] = full_out + pieces["short"] = full_out[:7] # maybe improved later + pieces["error"] = None + + branch_name, rc = runner(GITS, ["rev-parse", "--abbrev-ref", "HEAD"], + cwd=root) + # --abbrev-ref was added in git-1.6.3 + if rc != 0 or branch_name is None: + raise NotThisMethod("'git rev-parse --abbrev-ref' returned error") + branch_name = branch_name.strip() + + if branch_name == "HEAD": + # If we aren't exactly on a branch, pick a branch which represents + # the current commit. If all else fails, we are on a branchless + # commit. + branches, rc = runner(GITS, ["branch", "--contains"], cwd=root) + # --contains was added in git-1.5.4 + if rc != 0 or branches is None: + raise NotThisMethod("'git branch --contains' returned error") + branches = branches.split("\n") + + # Remove the first line if we're running detached + if "(" in branches[0]: + branches.pop(0) + + # Strip off the leading "* " from the list of branches. + branches = [branch[2:] for branch in branches] + if "master" in branches: + branch_name = "master" + elif not branches: + branch_name = None + else: + # Pick the first branch that is returned. Good or bad. + branch_name = branches[0] + + pieces["branch"] = branch_name + + # parse describe_out. It will be like TAG-NUM-gHEX[-dirty] or HEX[-dirty] + # TAG might have hyphens. + git_describe = describe_out + + # look for -dirty suffix + dirty = git_describe.endswith("-dirty") + pieces["dirty"] = dirty + if dirty: + git_describe = git_describe[:git_describe.rindex("-dirty")] + + # now we have TAG-NUM-gHEX or HEX + + if "-" in git_describe: + # TAG-NUM-gHEX + mo = re.search(r'^(.+)-(\d+)-g([0-9a-f]+)$', git_describe) + if not mo: + # unparsable. Maybe git-describe is misbehaving? + pieces["error"] = ("unable to parse git-describe output: '%s'" + % describe_out) + return pieces + + # tag + full_tag = mo.group(1) + if not full_tag.startswith(tag_prefix): + if verbose: + fmt = "tag '%s' doesn't start with prefix '%s'" + print(fmt % (full_tag, tag_prefix)) + pieces["error"] = ("tag '%s' doesn't start with prefix '%s'" + % (full_tag, tag_prefix)) + return pieces + pieces["closest-tag"] = full_tag[len(tag_prefix):] + + # distance: number of commits since tag + pieces["distance"] = int(mo.group(2)) + + # commit: short hex revision ID + pieces["short"] = mo.group(3) + + else: + # HEX: no tags + pieces["closest-tag"] = None + out, rc = runner(GITS, ["rev-list", "HEAD", "--left-right"], cwd=root) + pieces["distance"] = len(out.split()) # total number of commits + + # commit date: see ISO-8601 comment in git_versions_from_keywords() + date = runner(GITS, ["show", "-s", "--format=%ci", "HEAD"], cwd=root)[0].strip() + # Use only the last line. Previous lines may contain GPG signature + # information. + date = date.splitlines()[-1] + pieces["date"] = date.strip().replace(" ", "T", 1).replace(" ", "", 1) + + return pieces + + +def plus_or_dot(pieces: Dict[str, Any]) -> str: + """Return a + if we don't already have one, else return a .""" + if "+" in pieces.get("closest-tag", ""): + return "." + return "+" + + +def render_pep440(pieces: Dict[str, Any]) -> str: + """Build up version string, with post-release "local version identifier". + + Our goal: TAG[+DISTANCE.gHEX[.dirty]] . Note that if you + get a tagged build and then dirty it, you'll get TAG+0.gHEX.dirty + + Exceptions: + 1: no tags. git_describe was just HEX. 0+untagged.DISTANCE.gHEX[.dirty] + """ + if pieces["closest-tag"]: + rendered = pieces["closest-tag"] + if pieces["distance"] or pieces["dirty"]: + rendered += plus_or_dot(pieces) + rendered += "%d.g%s" % (pieces["distance"], pieces["short"]) + if pieces["dirty"]: + rendered += ".dirty" + else: + # exception #1 + rendered = "0+untagged.%d.g%s" % (pieces["distance"], + pieces["short"]) + if pieces["dirty"]: + rendered += ".dirty" + return rendered + + +def render_pep440_branch(pieces: Dict[str, Any]) -> str: + """TAG[[.dev0]+DISTANCE.gHEX[.dirty]] . + + The ".dev0" means not master branch. Note that .dev0 sorts backwards + (a feature branch will appear "older" than the master branch). + + Exceptions: + 1: no tags. 0[.dev0]+untagged.DISTANCE.gHEX[.dirty] + """ + if pieces["closest-tag"]: + rendered = pieces["closest-tag"] + if pieces["distance"] or pieces["dirty"]: + if pieces["branch"] != "master": + rendered += ".dev0" + rendered += plus_or_dot(pieces) + rendered += "%d.g%s" % (pieces["distance"], pieces["short"]) + if pieces["dirty"]: + rendered += ".dirty" + else: + # exception #1 + rendered = "0" + if pieces["branch"] != "master": + rendered += ".dev0" + rendered += "+untagged.%d.g%s" % (pieces["distance"], + pieces["short"]) + if pieces["dirty"]: + rendered += ".dirty" + return rendered + + +def pep440_split_post(ver: str) -> Tuple[str, Optional[int]]: + """Split pep440 version string at the post-release segment. + + Returns the release segments before the post-release and the + post-release version number (or -1 if no post-release segment is present). + """ + vc = str.split(ver, ".post") + return vc[0], int(vc[1] or 0) if len(vc) == 2 else None + + +def render_pep440_pre(pieces: Dict[str, Any]) -> str: + """TAG[.postN.devDISTANCE] -- No -dirty. + + Exceptions: + 1: no tags. 0.post0.devDISTANCE + """ + if pieces["closest-tag"]: + if pieces["distance"]: + # update the post release segment + tag_version, post_version = pep440_split_post(pieces["closest-tag"]) + rendered = tag_version + if post_version is not None: + rendered += ".post%d.dev%d" % (post_version + 1, pieces["distance"]) + else: + rendered += ".post0.dev%d" % (pieces["distance"]) + else: + # no commits, use the tag as the version + rendered = pieces["closest-tag"] + else: + # exception #1 + rendered = "0.post0.dev%d" % pieces["distance"] + return rendered + + +def render_pep440_post(pieces: Dict[str, Any]) -> str: + """TAG[.postDISTANCE[.dev0]+gHEX] . + + The ".dev0" means dirty. Note that .dev0 sorts backwards + (a dirty tree will appear "older" than the corresponding clean one), + but you shouldn't be releasing software with -dirty anyways. + + Exceptions: + 1: no tags. 0.postDISTANCE[.dev0] + """ + if pieces["closest-tag"]: + rendered = pieces["closest-tag"] + if pieces["distance"] or pieces["dirty"]: + rendered += ".post%d" % pieces["distance"] + if pieces["dirty"]: + rendered += ".dev0" + rendered += plus_or_dot(pieces) + rendered += "g%s" % pieces["short"] + else: + # exception #1 + rendered = "0.post%d" % pieces["distance"] + if pieces["dirty"]: + rendered += ".dev0" + rendered += "+g%s" % pieces["short"] + return rendered + + +def render_pep440_post_branch(pieces: Dict[str, Any]) -> str: + """TAG[.postDISTANCE[.dev0]+gHEX[.dirty]] . + + The ".dev0" means not master branch. + + Exceptions: + 1: no tags. 0.postDISTANCE[.dev0]+gHEX[.dirty] + """ + if pieces["closest-tag"]: + rendered = pieces["closest-tag"] + if pieces["distance"] or pieces["dirty"]: + rendered += ".post%d" % pieces["distance"] + if pieces["branch"] != "master": + rendered += ".dev0" + rendered += plus_or_dot(pieces) + rendered += "g%s" % pieces["short"] + if pieces["dirty"]: + rendered += ".dirty" + else: + # exception #1 + rendered = "0.post%d" % pieces["distance"] + if pieces["branch"] != "master": + rendered += ".dev0" + rendered += "+g%s" % pieces["short"] + if pieces["dirty"]: + rendered += ".dirty" + return rendered + + +def render_pep440_old(pieces: Dict[str, Any]) -> str: + """TAG[.postDISTANCE[.dev0]] . + + The ".dev0" means dirty. + + Exceptions: + 1: no tags. 0.postDISTANCE[.dev0] + """ + if pieces["closest-tag"]: + rendered = pieces["closest-tag"] + if pieces["distance"] or pieces["dirty"]: + rendered += ".post%d" % pieces["distance"] + if pieces["dirty"]: + rendered += ".dev0" + else: + # exception #1 + rendered = "0.post%d" % pieces["distance"] + if pieces["dirty"]: + rendered += ".dev0" + return rendered + + +def render_git_describe(pieces: Dict[str, Any]) -> str: + """TAG[-DISTANCE-gHEX][-dirty]. + + Like 'git describe --tags --dirty --always'. + + Exceptions: + 1: no tags. HEX[-dirty] (note: no 'g' prefix) + """ + if pieces["closest-tag"]: + rendered = pieces["closest-tag"] + if pieces["distance"]: + rendered += "-%d-g%s" % (pieces["distance"], pieces["short"]) + else: + # exception #1 + rendered = pieces["short"] + if pieces["dirty"]: + rendered += "-dirty" + return rendered + + +def render_git_describe_long(pieces: Dict[str, Any]) -> str: + """TAG-DISTANCE-gHEX[-dirty]. + + Like 'git describe --tags --dirty --always -long'. + The distance/hash is unconditional. + + Exceptions: + 1: no tags. HEX[-dirty] (note: no 'g' prefix) + """ + if pieces["closest-tag"]: + rendered = pieces["closest-tag"] + rendered += "-%d-g%s" % (pieces["distance"], pieces["short"]) + else: + # exception #1 + rendered = pieces["short"] + if pieces["dirty"]: + rendered += "-dirty" + return rendered + + +def render(pieces: Dict[str, Any], style: str) -> Dict[str, Any]: + """Render the given version pieces into the requested style.""" + if pieces["error"]: + return {"version": "unknown", + "full-revisionid": pieces.get("long"), + "dirty": None, + "error": pieces["error"], + "date": None} + + if not style or style == "default": + style = "pep440" # the default + + if style == "pep440": + rendered = render_pep440(pieces) + elif style == "pep440-branch": + rendered = render_pep440_branch(pieces) + elif style == "pep440-pre": + rendered = render_pep440_pre(pieces) + elif style == "pep440-post": + rendered = render_pep440_post(pieces) + elif style == "pep440-post-branch": + rendered = render_pep440_post_branch(pieces) + elif style == "pep440-old": + rendered = render_pep440_old(pieces) + elif style == "git-describe": + rendered = render_git_describe(pieces) + elif style == "git-describe-long": + rendered = render_git_describe_long(pieces) + else: + raise ValueError("unknown style '%s'" % style) + + return {"version": rendered, "full-revisionid": pieces["long"], + "dirty": pieces["dirty"], "error": None, + "date": pieces.get("date")} + + +def get_versions() -> Dict[str, Any]: + """Get version information or return default if unable to do so.""" + # I am in _version.py, which lives at ROOT/VERSIONFILE_SOURCE. If we have + # __file__, we can work backwards from there to the root. Some + # py2exe/bbfreeze/non-CPython implementations don't do __file__, in which + # case we can only use expanded keywords. + + cfg = get_config() + verbose = cfg.verbose + + try: + return git_versions_from_keywords(get_keywords(), cfg.tag_prefix, + verbose) + except NotThisMethod: + pass + + try: + root = os.path.realpath(__file__) + # versionfile_source is the relative path from the top of the source + # tree (where the .git directory might live) to this file. Invert + # this to find the root from __file__. + for _ in cfg.versionfile_source.split('/'): + root = os.path.dirname(root) + except NameError: + return {"version": "0+unknown", "full-revisionid": None, + "dirty": None, + "error": "unable to find root of source tree", + "date": None} + + try: + pieces = git_pieces_from_vcs(cfg.tag_prefix, root, verbose) + return render(pieces, cfg.style) + except NotThisMethod: + pass + + try: + if cfg.parentdir_prefix: + return versions_from_parentdir(cfg.parentdir_prefix, root, verbose) + except NotThisMethod: + pass + + return {"version": "0+unknown", "full-revisionid": None, + "dirty": None, + "error": "unable to compute version", "date": None} diff --git a/pyproject.toml b/pyproject.toml index f7ca374..6e964f3 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -7,8 +7,8 @@ requires = [ build-backend = "setuptools.build_meta" [project] -name = "pyiron_module_template" -description = "pyiron_module_template - Your pyiron-like module." +name = "pyiron_snippets" +description = "pyiron_snippets - Short, dependency-free python snippets." readme = "docs/README.md" keywords = [ "pyiron",] requires-python = ">=3.9, <3.13" @@ -28,7 +28,8 @@ dependencies = [ ] dynamic = [ "version",] authors = [ - { name = "Lorem Ipsum", email = "lorem@ipsum.com" }, + { name = "Liam Huber", email = "liamhuber@greyhavensolutions.com" }, + { name = "Sam Waseda", email = "o.waseda@mpie.de" } ] [project.license] @@ -36,18 +37,18 @@ file = "LICENSE" [project.urls] Homepage = "https://pyiron.org/" -Documentation = "https://pyiron_module_template.readthedocs.io" -Repository = "https://github.com/pyiron/pyiron_module_template" +Documentation = "https://pyiron_snippets.readthedocs.io" +Repository = "https://github.com/pyiron/pyiron_snippets" [tool.versioneer] VCS = "git" style = "pep440-pre" -versionfile_source = "pyiron_module_template/_version.py" -parentdir_prefix = "pyiron_module_template" -tag_prefix = "pyiron_module_template-" +versionfile_source = "pyiron_snippets/_version.py" +parentdir_prefix = "pyiron_snippets" +tag_prefix = "pyiron_snippets-" [tool.setuptools.packages.find] -include = [ "pyiron_module_template*",] +include = [ "pyiron_snippets*",] [tool.setuptools.dynamic.version] -attr = "pyiron_module_template.__version__" +attr = "pyiron_snippets.__version__" diff --git a/tests/unit/test_tests.py b/tests/unit/test_tests.py index 2d9f5a8..71876c7 100644 --- a/tests/unit/test_tests.py +++ b/tests/unit/test_tests.py @@ -1,9 +1,9 @@ import unittest -import pyiron_module_template +import pyiron_snippets class TestVersion(unittest.TestCase): def test_version(self): - version = pyiron_module_template.__version__ + version = pyiron_snippets.__version__ print(version) self.assertTrue(version.startswith('0')) diff --git a/update_module_name.sh b/update_module_name.sh deleted file mode 100644 index 4255b49..0000000 --- a/update_module_name.sh +++ /dev/null @@ -1,28 +0,0 @@ -#!/bin/bash -# Mac users: You [may first need to install gnu-sed](https://github.com/MigleSur/GenAPI/issues/8) - -module_name="pyiron_IntendedModuleName" -rst_delimit="=========================" # This should be as many '=' as the name length. - -for file in .binder/postBuild \ - .github/ISSUE_TEMPLATE/*.md \ - docs/conf.py \ - docs/index.rst \ - notebooks/version.ipynb \ - tests/unit/test_tests.py \ - .coveragerc \ - .gitattributes \ - MANIFEST.in \ - setup.cfg \ - setup.py -do - sed -i "s/pyiron_module_template/${module_name}/g" ${file} - sed -i "s/======================/${rst_delimit}/g" ${file} -done - - -mv pyiron_module_template ${module_name} - -python -m versioneer setup - -rm update_module_name.sh