{"id":26520629,"url":"https://github.com/jlorieau/geomancy","last_synced_at":"2026-04-04T22:33:04.795Z","repository":{"id":182525717,"uuid":"668418863","full_name":"jlorieau/geomancy","owner":"jlorieau","description":"Validate and check development, testing and production environments","archived":false,"fork":false,"pushed_at":"2023-08-10T16:47:50.000Z","size":444,"stargazers_count":2,"open_issues_count":13,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-11-27T14:52:05.680Z","etag":null,"topics":["checker","dotenv","dotenv-linter","environment","environment-variables","environments","python3","settings","settings-management","setup","testing","validation"],"latest_commit_sha":null,"homepage":"https://geomancy.readthedocs.io/en/latest/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jlorieau.png","metadata":{"files":{"readme":"README.md","changelog":"changelog/_template.rst","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2023-07-19T19:00:28.000Z","updated_at":"2025-08-27T12:34:45.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/jlorieau/geomancy","commit_stats":{"total_commits":482,"total_committers":1,"mean_commits":482.0,"dds":0.0,"last_synced_commit":"3f0e2562cf1679823d2dfd7c60f077bcac712783"},"previous_names":["jlorieau/geomancy"],"tags_count":13,"template":false,"template_full_name":null,"purl":"pkg:github/jlorieau/geomancy","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jlorieau%2Fgeomancy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jlorieau%2Fgeomancy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jlorieau%2Fgeomancy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jlorieau%2Fgeomancy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jlorieau","download_url":"https://codeload.github.com/jlorieau/geomancy/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jlorieau%2Fgeomancy/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31416774,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-04T20:09:54.854Z","status":"ssl_error","status_checked_at":"2026-04-04T20:09:44.350Z","response_time":60,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["checker","dotenv","dotenv-linter","environment","environment-variables","environments","python3","settings","settings-management","setup","testing","validation"],"created_at":"2025-03-21T12:23:02.111Z","updated_at":"2026-04-04T22:33:04.775Z","avatar_url":"https://github.com/jlorieau.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003c!-- start logo --\u003e\n\u003cimg src=\"https://raw.githubusercontent.com/jlorieau/geomancy/main/docs/_static/geomancy_logo.svg\" alt=\"geomancy logo\" height=\"150px\"/\u003e\n\u003c!-- end logo --\u003e\n\n\u003c!-- start badges --\u003e\n[![pypi version](https://img.shields.io/pypi/v/geomancy.svg)](https://pypi.org/project/geomancy/)\n[![python versions](https://img.shields.io/pypi/pyversions/geomancy.svg)](https://pypi.org/project/geomancy/)\n[![Black formatting](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)\n[![Documentation Status](https://readthedocs.org/projects/geomancy/badge/?version=latest)](https://geomancy.readthedocs.io/en/latest/?badge=latest)\n\u003c!-- end badges --\u003e\n\u003c!-- start intro --\u003e\nGeomancy makes it easy to check and validate environments, such as development,\ntesting and production.\n\nEnvironment checks and tests are helpful for testing the correct setting\nof environment variables, the installation and versions of installed\nexecutables, the state of external dependencies, like LaTeX packages, or cloud\nresources, or for checking environments that use the\n[12-factor](http://12factor.net/) principles.\n\u003c!-- end intro --\u003e\n\n## Features\n\n\u003c!-- start features --\u003e\n\n### Capabilities\n\n\u003cp\u003e\n\u003cdetails\u003e\n\u003csummary\u003e\n\u003cstrong\u003e\u003cu\u003eValidation of layered and combined environments\u003c/u\u003e\u003c/strong\u003e\n\u003c/summary\u003e\n\nLayered environments could include a _common_ or _base_ environment, with\nadditional checks for settings of _test_, _development_ and _production_\nenvironments.\n\nIn the following checks file, the existence of an environment file and a secrets\nfile can be checked based on the ``$ENV`` environment variable. (See the\n[docker environment variable parameter expansion rules](https://docs.docker.com/compose/environment-variables/env-file/#parameter-expansion))\n\n```yaml\nchecks:\n  Environment:\n    desc: Check environment variables in different deployments\n\n    CheckEnvFile:\n      desc: Check the existence of the environment file\n      checkPath: \"deployments/${ENV}/.env\"\n\n    CheckSecretsFile:\n      desc: Check the existence of the secrets file\n      checkPath: \"deployments/${ENV}/.secrets\"\n```\n\nThis check file can be used to check multiple environments:\n\n```shell\n# check \"dev\" environment\n$ geo -e deployments/base/.env -e deployments/dev/.env checks.yaml\n...\n# check \"test\" environment\n$ geo -e deployments/base/.env -e deployments/test/.env checks.yaml\n...\n```\nIn this case, ``deployments/dev/.env`` is an\n[environment file](https://docs.docker.com/compose/environment-variables/env-file/)\nthat sets ``ENV=dev``, ``deployments/test/.env`` is an\n[environment file](https://docs.docker.com/compose/environment-variables/env-file/)\nthat sets ``ENV=test``.\n\u003c/details\u003e\n\u003c/p\u003e\n\n\u003cp\u003e\n\u003cdetails\u003e\n\u003csummary\u003e\n\u003cstrong\u003e\u003cu\u003eFull environment file support\u003c/u\u003e\u003c/strong\u003e of the docker\n\u003ca href=\"https://docs.docker.com/compose/environment-variables/env-file/\"\u003eenv file syntax\u003c/a\u003e\n\u003c/summary\u003e\n\nEnvironment files are loaded using the ``-e/--env`` option,\nwhich can be layered for different environments.\n\n```shell\n# Run checks for 'dev' environment\n$ geo -e deployments/base/.env -e deployments/dev/.env check\n...\n# Run checks for 'test' environment\n$ geo -e base.env -e test.env run -- echo \"Test environment\"\n```\n\u003c/details\u003e\n\u003c/p\u003e\n\n\u003cp\u003e\n\u003cdetails\u003e\n\u003csummary\u003e\n\u003cstrong\u003e\u003cu\u003eConcurrent checks with multiple threads\u003c/u\u003e\u003c/strong\u003e to quickly probe\nI/O bound resources\n\u003c/summary\u003e\n\nThe following example concurrently checks that the 3 AWS S3 buckets are\naccessible using the\n[current credentials](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-files.html)\nand are secured.\n\nThis example is in yaml format, and checks can be formatted in toml format\nas well.\n\n```yaml\nAWS:\n  TemplateS3:\n    checkS3: myproject-cfn-templates\n  StaticS3:\n    checkS3: myproject-static\n  MediaS3:\n    checkS3: myproject-media\n\n```\n\u003c/details\u003e\n\u003c/p\u003e\n\n\u003cp\u003e\n\u003cdetails\u003e\n\u003csummary\u003e\n\u003cstrong\u003e\u003cu\u003eLoad checks in multiple formats\u003c/u\u003e\u003c/strong\u003e\n\u003c/summary\u003e\n\nIncluding [yaml](https://yaml.org) (e.g. ``.geomancy.yaml``)\n\n```yaml\nchecks:\n  Environment:\n    desc: Check environment variables common to all development environments\n\n    Path:\n      decs: Search paths for executables\n      checkEnv: $PATH\n```\n\nor [toml](https://toml.io/en/) (e.g. ``.geomancy.toml``)\n\n```toml\n[checks.Environment]\ndesc = \"Check environment variables common to all development environments\"\n\n    [checks.Environment.Path]\n    desc = \"Search paths for executables\"\n    checkEnv = \"$PATH\"\n```\n\nor [toml](https://toml.io/en/) with each check on 1 line (e.g. ``.geomancy.toml``)\n\n```toml\n[Checks.Environment]\nPath = {checkEnv = \"$PATH\", desc = \"Search paths for executables\"}\n```\n\nor [pyproject.toml](https://peps.python.org/pep-0621/)\n\n```toml\n[tool.geomancy.checks.Environment]\ndesc = \"Check environment variables common to all development environments\"\n\n    [tool.geomancy.checks.Environment.Path]\n    desc = \"Search paths for executables\"\n    checkEnv = \"$PATH\"\n```\n\n\u003c/details\u003e\n\u003c/p\u003e\n\n### Available Checks\n\n\u003cp\u003e\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003e\u003cu\u003eOperating systems\u003c/u\u003e\u003c/strong\u003e meet the minimum required\n  versions\n  (\u003ca href=\"https://geomancy.readthedocs.io/en/latest/usage/format.html#checkplatform\"\u003echeckOS\u003c/a\u003e)\n\u003c/summary\u003e\n\nThe following shows an example in yaml format. Checks can be formatted in\ntoml format as well.\n\n```yaml\nOperatingSystem:\n  desc: Check the minimum operating system versions\n  subchecks: any\n\n  checkMacOS:\n    desc: MacOS 10.9 or later (released 2013)\n    checkOS: \"macOS \u003e= 10.9\"\n  checkLinuxOS:\n    desc: Linux 4.0 or later (released 2015)\n    checkOS: \"Linux \u003e= 3.0\"\n  checkWindows:\n    desc: Windows 10 or later (released 2015)\n    checkOS: \"Windows \u003e= 10\"\n```\n\u003c/details\u003e\n\u003c/p\u003e\n\n\u003cp\u003e\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003e\u003cu\u003eEnvironment variables\u003c/u\u003e\u003c/strong\u003e are properly set and\n  have valid values with regular expressions\n  (\u003ca href=\"https://geomancy.readthedocs.io/en/latest/usage/format.html#checkenv\"\u003echeckEnv\u003c/a\u003e)\n\u003c/summary\u003e\n\nThe following shows an example in yaml format. Checks can be formatted in\ntoml format as well.\n\n```yaml\nUsername:\n  desc: The current username\n  checkEnv: \"$USER\"\n  regex: \"[a-z_][a-z0-9_-]*[$]?\"\n```\n\u003c/details\u003e\n\u003c/p\u003e\n\n\u003cp\u003e\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003e\u003cu\u003ePaths\u003c/u\u003e\u003c/strong\u003e exist and they're the right type\n  (\u003ca href=\"https://geomancy.readthedocs.io/en/latest/usage/format.html#checkpath\"\u003echeckPath\u003c/a\u003e)\n\u003c/summary\u003e\n\nThe following shows an example in yaml format. Checks can be formatted in\ntoml format as well.\n\n```yaml\nPyprojectToml:\n  desc: A project's pyprojectfile\n  checkPath: ./pyproject.toml\n  type: file\n```\n\u003c/details\u003e\n\u003c/p\u003e\n\n\u003cp\u003e\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003e\u003cu\u003eExecutables\u003c/u\u003e\u003c/strong\u003e are available and meet minimum\n  or correct versions\n  (\u003ca href=\"https://geomancy.readthedocs.io/en/latest/usage/format.html#checkexec\"\u003echeckExec\u003c/a\u003e)\n\u003c/summary\u003e\n\nThe following shows an example in yaml format. Checks can be formatted in\ntoml format as well.\n\n```yaml\nPython:\n  desc: Python interpreter (version 3.11 or higher)\n  checkExec: \"python3\u003e=3.11\"\n```\n\u003c/details\u003e\n\u003c/p\u003e\n\n\u003cp\u003e\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003e\u003cu\u003ePython packages\u003c/u\u003e\u003c/strong\u003e are available minimum or\n  correct versions\n  (\u003ca href=\"https://geomancy.readthedocs.io/en/latest/usage/format.html#checkpythonpkg\"\u003echeckPythonPkg\u003c/a\u003e)\n\u003c/summary\u003e\n\nThe following shows an example in yaml format. Checks can be formatted in\ntoml format as well.\n\n```yaml\nPythonPackages:\n  geomancy:\n    desc: Geomancy python package\n    checkPythonPkg: \"geomancy\u003e=0.1\"\n```\n\u003c/details\u003e\n\u003c/p\u003e\n\n\u003cp\u003e\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003e\u003cu\u003eGroup checks\u003c/u\u003e\u003c/strong\u003e and specify\n  conditional (all or any) pass criteria\n  (\u003ca href=\"https://geomancy.readthedocs.io/en/latest/usage/format.html#check-groups\"\u003eGroups of Checks\u003c/a\u003e)\n\u003c/summary\u003e\n\nThe following shows an example with the ``checks`` group containing 2 groups,\n``OperatingSystem``, ``Environment``.\n\nThe ``OperatingSystem`` group contains 3 checks: ``checkMacOS``,\n``checkLinuxOS``, ``checkWindows``, and the ``OperatingSystem`` group check\npasses if any of these 3 checks pass (``subchecks: any``)\n\nThe ``Environment`` group contains 1 check, ``Path``, and 1 group, ``Username``,\nwhich itself contains 2 checks: ``UnixUsername`` and ``WindowsUsername``.\n\nThis example is in yaml format, and checks can be formatted in toml format\nas well.\n\n```yaml\nchecks:\n  OperatingSystem:\n    desc: Check the minimum operating system versions\n    subchecks: any\n\n    checkMacOS:\n      desc: MacOS 10.9 or later (released 2013)\n      checkOS: \"macOS \u003e= 10.9\"\n    checkLinuxOS:\n      desc: Linux 4.0 or later (released 2015)\n      checkOS: \"Linux \u003e= 3.0\"\n    checkWindows:\n      desc: Windows 10 or later (released 2015)\n      checkOS: \"Windows \u003e= 10\"\n\n  Environment:\n    desc: Check environment variables common to all development environments\n\n    Path:\n      decs: Paths to search for executables\n      checkEnv: $PATH\n    Username:\n      subchecks: any\n\n      UnixUsername:  # Username on linux and macOS\n        desc: The current username\n        checkEnv: $USER\n        regex: \"[a-z_][a-z0-9_-]*[$]?\"\n      WindowsUsername:  # Username on Windows\n        desc: The current username\n        checkEnv: $USERNAME\n        regex: \"[a-z_][a-z0-9_-]*[$]?\"\n\n```\n\u003c/details\u003e\n\u003c/p\u003e\n\n\u003cp\u003e\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003e\u003cu\u003eAWS\u003c/u\u003e\u003c/strong\u003e resources exist and are securely setup\n  (\u003ca href=\"https://geomancy.readthedocs.io/en/latest/usage/checks/aws/index.html\"\u003eAWS checks\u003c/a\u003e)\n\u003c/summary\u003e\n\nThe following shows an example in yaml format. Checks can be formatted in\ntoml format as well.\n\n```yaml\nAWS:\n  IAM:\n    desc: Check the default authentication and security settings\n    checkIAM:\n\n  TemplatesS3Bucket:\n    desc: Check the bucket for cloudformation templates\n    checkS3: \"myproject-cfn-templates\"\n```\n\u003c/details\u003e\n\u003c/p\u003e\n\n\u003c!-- end features --\u003e\n\n## Quickstart\n\u003c!-- start quickstart --\u003e\n1. Create a ``.geomancy.yaml`` file with checks. See\n   [examples/geomancy.yaml](https://github.com/jlorieau/geomancy/blob/main/examples/geomancy.yaml)\n   for an example of all checks.\n\n    ```yaml\n    Environment:\n      desc: Check environment variables common to all development environments\n\n      Username:\n        desc: The current username\n        checkEnv: \"$USER\"\n        regex: \"[a-z_][a-z0-9_-]*[$]?\"\n\n    Paths:\n      desc: Checks the existence of needed files and directories\n      subchecks: \"any\" # at least one of the files must be present\n\n      Geomancy:\n        desc: Check for the 'geomancy.toml' file\n        checkPath: examples/geomancy.toml\n        type: file\n      Pyproject:\n        desc: Check for 'pyproject.toml' file\n        checkPath: examples/pyproject.toml\n        type: file\n\n    Executables:\n      desc: Check the availability of commands and their versions\n\n      Python:\n        desc: Python interpreter ver 3.11 or higher\n        checkExec: python3\u003e=3.11\n    ```\n\n2. Use ``geo`` to run the checks.\n\n    ```shell\n     [✔] test.yaml...passed\n     [✔]   Environment...passed\n     [✔]     Check environment variable '$USER'...passed\n     [✔]   Paths...passed\n     [✔]     Check path 'examples/geomancy.toml'...passed\n     [✔]     Check path 'examples/pyproject.toml'...passed\n     [✔]   Executables...passed\n     [✔]     Check executable 'python3\u003e=3.11'...passed\n    ================================= 8 passed in 0.50s ==================================\n    ```\n\n    (By default, ``geomancy`` will search ``.geomancy.y[a]ml``, ``geomancy.y[a]ml``\n    ``.geomancy.toml``, ``geomancy.toml`` and ``pyproject.toml``.)\n\u003c!-- end quickstart --\u003e\n\n\n## Documentation\n\nFor full documentation please see https://geomancy.readthedocs.io/en/latest.\n\n\n## Bugs or Requests\nPlease use the [GitHub issue tracker](https://github.com/jlorieau/geomancy/issues)\nto submit bugs or request features.\n\n## Similar projects\n\nThe following projects share some of the same goals in different contexts:\n\n- [Envalid](https://github.com/af/envalid)\n- [AWS Config](https://aws.amazon.com/config/)\n\n## License\n\nCopyright Justin Lorieau and others, 2023.\n\nDistributed under the terms of the [MIT license](LICENSE).\ngeomancy is free and open source software.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjlorieau%2Fgeomancy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjlorieau%2Fgeomancy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjlorieau%2Fgeomancy/lists"}