cf-regions 0.1.0__tar.gz

cf_regions-0.1.0/AUTHORS.md

@@ -0,0 +1,9 @@
+# Authors and maintainers
+
+`cf-regions` was initiated and originally developed by [Yves Sorge](https://github.com/ysorge), who serves as its
+initial author and maintainer.
+
+Additional contributors are recorded in the repository history and release
+notes. Maintainer responsibility may move to another person or organization
+without changing or erasing authorship of existing contributions. Current
+maintainers should be identified in the repository and package metadata.

cf_regions-0.1.0/CHANGELOG.md

@@ -0,0 +1,32 @@
+# Changelog
+
+All notable changes to `cf-regions` are documented here. The project follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and uses
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## 0.1.0
+
+This is the first public release.
+
+### Added
+
+- Version-aware access to CF Standardized Region Lists 1 through 5.
+- Offline coordinate lookup, hierarchy traversal, region metadata, interpreted
+  GeoJSON geometry, and detailed mapping provenance.
+- Typed Python API and shell-friendly CLI with separate names, table, JSON, and
+  JSONL output formats.
+- Declarative, versioned spatial-interpretation profiles with optional file
+  integrity checksums, additive external profile directories, and discovery
+  APIs.
+- Low- and high-detail shapes plus GeoJSON, WKT, WKB, and WKB-hex exports.
+- High-detail coordinate lookup with an optional generated spatial index and
+  lazy geometry decoding; plain GeoJSON profiles remain fully supported.
+- Reproducible dataset tooling, JSON Schemas, tests, type checks, and packaging
+  validation.
+
+### Documentation
+
+- Document data sources, mapping behavior, known limitations, profile authoring,
+  and the maintenance workflow.
+- Keep the README focused on installation and first use, with detailed Python
+  API and command-line guides under `docs/`.

cf_regions-0.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,27 @@
+# Code of conduct
+
+The `cf-regions` project is committed to an open, welcoming, inclusive, and
+harassment-free community. Participants are expected to follow the standards of
+the [Contributor Covenant, version 2.1][covenant] in discussions, issues, pull
+requests, reviews, and project events.
+
+## Expected behavior
+
+- Be respectful of different backgrounds, viewpoints, and levels of experience.
+- Give and accept constructive technical feedback with empathy.
+- Focus disagreement on ideas and evidence rather than people.
+- Accept responsibility for mistakes and work to repair their impact.
+
+Harassment, discriminatory or sexualized language, threats, trolling, personal
+attacks, and publishing another person's private information are not acceptable.
+
+## Reporting and enforcement
+
+Report conduct concerns privately through the repository's [private reporting
+channel][private-report]. Do not disclose sensitive details in a public issue.
+Maintainers will review reports as promptly and impartially as possible, protect
+the reporter's privacy, and may edit or remove contributions, issue warnings, or
+temporarily or permanently restrict participation.
+
+[covenant]: https://www.contributor-covenant.org/version/2/1/code_of_conduct/
+[private-report]: https://github.com/ysorge/cf-regions/security/advisories/new

cf_regions-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,49 @@
+# Contributing
+
+Contributions are welcome through GitHub issues and pull requests. Please open
+an issue before substantial features, public API changes, or new spatial
+interpretations so the approach and scope can be discussed. Small fixes and
+documentation improvements may be submitted directly.
+
+Participation is governed by the [Code of conduct](CODE_OF_CONDUCT.md).
+
+## Development setup
+
+Use one of the latest Python versions in a virtual environment:
+
+```console
+python -m venv .venv
+.venv/bin/python -m pip install -e ".[dev]"
+```
+
+On Windows, use `.venv\Scripts\python` instead. Before opening a pull 
+request, run:
+
+```console
+ruff check src tests tools
+mypy src
+pytest --cov=cfregions --cov-report=term-missing
+python -m build
+twine check dist/*
+```
+
+Keep the core free of web and GUI dependencies. Public API changes need tests
+and a changelog entry. Prefer small, typed functions and preserve separation
+between data loading, indexed domain logic, the Python API, and the CLI.
+
+## Vocabulary, geometry, and hierarchy changes
+
+CF supplies standardized names, not official boundaries. Spatial-interpretation
+changes must include a stable source and compatible license, a pinned version,
+a reproducible derivation method, updated attribution and checksums, relevant
+tests, and documented limitations.
+
+Follow the [dataset maintenance workflow](docs/dataset-maintenance.md). Source
+roles are documented in [Data sources and mapping method](docs/data-sources-and-mapping.md),
+and normative design decisions are in the [mapping guidelines](docs/mapping-guidelines.md).
+Run `python tools/build_dataset.py --help` for builder inputs. Runtime lookup
+must remain fully offline.
+
+By contributing, you agree that your code contribution is distributed under
+Apache-2.0. Do not submit data or other material that cannot be redistributed
+under the terms documented in `DATA_LICENSES.md`.

cf_regions-0.1.0/DATA_LICENSES.md

@@ -0,0 +1,153 @@
+# Data licenses and attribution
+
+The `cf-regions` source code is Apache-2.0. The bundled geometry catalog is a
+collective/derived dataset assembled from the sources below. Upstream data is
+not relicensed under Apache-2.0; its original terms continue to apply.
+
+This file is the legal and attribution reference. For the technical role of
+each source and the lookup pipeline, see
+[Data sources and mapping method](docs/data-sources-and-mapping.md). Maintainers
+should follow [Dataset maintenance](docs/dataset-maintenance.md) when updating
+vocabularies, geometries, or hierarchy data.
+
+In the Python distribution's compound license expression,
+`LicenseRef-NASA-Open-Data` refers to the NASA ESDIS reuse basis documented
+below and `LicenseRef-Public-Domain` refers to the Natural Earth materials that
+their publisher dedicates to the public domain.
+
+## CF Standardized Region Lists v1–v5
+
+- Role: canonical identifiers and the few supplied descriptions
+- Versions/dates: 1 (12 December 2002), 2 (12 July 2013), 3 (11 July
+  2018), 4 (18 December 2018), and 5 (12 November 2024)
+- Sources: <https://cfconventions.org/Data/standardized-region-list/>
+- Terms: the CF website is made available under
+  [CC0 1.0](https://creativecommons.org/publicdomain/zero/1.0/); the exact XML
+  is retained in the package for validation and provenance.
+
+CF does not supply the boundaries in this project. Nothing here should be
+described as an official CF polygon.
+
+## NASA GCMD Location Keywords
+
+- Role: hierarchical location paths and connected-parent interpretation
+- Version/date: 24.8, revised 16 September 2026
+- Source: <https://gcmd.earthdata.nasa.gov/kms/concepts/concept_scheme/locations>
+- Reuse basis: NASA ESDIS content is generally not copyrighted, and unmarked
+  NASA-led data is provided under CC0 according to the
+  [NASA Earthdata Data Use and Citation Guidance](https://www.earthdata.nasa.gov/engage/open-data-services-software/data-use-policy).
+  NASA requests acknowledgment as the source.
+
+Only curated hierarchy paths and version metadata are included, not the full
+GCMD export. Composite-ocean and diagnostic-section connections supplement the
+GCMD paths and are identified as such in the manifest limitations.
+
+## SeaVoX Salt and Fresh Water Body Gazetteer polygons v19
+
+- Role: 31 exact marine-area interpretations and ocean hierarchy dissolves
+- Version: 19
+- Publisher: Flanders Marine Institute (VLIZ), Marine Regions
+- DOI: <https://doi.org/10.14284/590>
+- Download: <https://www.marineregions.org/download_file.php?name=SeaVoX_sea_areas_polygons_v19.zip>
+- License: [Creative Commons Attribution 4.0 International
+  (CC BY 4.0)](https://creativecommons.org/licenses/by/4.0/legalcode)
+
+Requested attribution:
+
+> Flanders Marine Institute (2023). SeaVoX Salt and Fresh Water Body Gazetteer.
+> Version 19. Available online at Marine Regions. DOI: 10.14284/590.
+
+The package selects or dissolves features through pinned MRGIDs, creates
+documented low- and high-detail simplifications for distribution, and records
+the selector in each feature. Both representations preserve the source-defined
+extent; in particular, no project-specific boundary is inserted between the
+North Sea and Baltic Sea. Marine
+Regions data is generalized and not intended for navigation or legal boundary
+determination. See <https://www.marineregions.org/disclaimer.php>.
+
+## Natural Earth
+
+- Role: continent/region polygons, lower-48 state polygons, lakes, global land
+  and ocean masks, and South China Sea
+- Scale and upstream versions: 1:50m; versions 4.1.0 through 5.1.1 as recorded by
+  layer in each feature
+- Source: <https://www.naturalearthdata.com/>
+- Terms: public domain, <https://www.naturalearthdata.com/about/terms-of-use/>
+
+Natural Earth reflects a generalized, de-facto boundary worldview. The
+`contiguous_united_states` feature is the union of the lower 48 states plus the
+District of Columbia and excludes Alaska and Hawaii.
+
+## OMIP protocol
+
+- Role: approximate endpoints for 16 ocean transport sections
+- Citation: Griffies et al. (2016), *OMIP contribution to CMIP6: experimental and
+  diagnostic protocol for the physical component of the Ocean Model
+  Intercomparison Project*, Geoscientific Model Development 9, 3231–3296
+- DOI: <https://doi.org/10.5194/gmd-9-3231-2016>
+- License: [CC BY 3.0](https://creativecommons.org/licenses/by/3.0/legalcode)
+
+The endpoints come from Appendix J, Table J1. The paper explicitly treats them
+as approximate and model-grid dependent. This project normalizes coordinate
+order to longitude/latitude, maps paper labels to canonical CF names, and
+encodes the endpoints as GeoJSON lines.
+
+## CMIP6 CMOR tables
+
+- Role: Canadian Archipelago diagnostic section and the sea-ice Fram Strait
+  variant
+- Source: <https://github.com/PCMDI/cmip6-cmor-tables>
+- License: BSD-3-Clause
+
+This project extracts two endpoint definitions, corrects the upstream Canadian
+Archipelago spelling to the canonical CF spelling, and combines the two Fram
+Strait contexts in one `MultiLineString`.
+
+The required upstream notice follows:
+
+> BSD 3-Clause License
+>
+> Copyright (c) 2017, PCMDI (Program for Climate Model Diagnosis and
+> Intercomparison). All rights reserved.
+>
+> Redistribution and use in source and binary forms, with or without
+> modification, are permitted provided that the following conditions are met:
+>
+> 1. Redistributions of source code must retain the above copyright notice,
+> this list of conditions and the following disclaimer.
+> 2. Redistributions in binary form must reproduce the above copyright notice,
+> this list of conditions and the following disclaimer in the documentation
+> and/or other materials provided with the distribution.
+> 3. Neither the name of the copyright holder nor the names of its contributors
+> may be used to endorse or promote products derived from this software without
+> specific prior written permission.
+>
+> THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+> AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+> IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+> ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+> LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+> CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+> SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+> INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+> CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+> ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+> POSSIBILITY OF SUCH DAMAGE.
+
+## Project-authored and derived geometry
+
+Analytical world/hemisphere boxes are project-authored under Apache-2.0.
+Composite geometries retain the applicable upstream data terms. The
+Indo-Pacific mask is explicitly an interpretation of the CF description, not an
+upstream authoritative boundary.
+
+## Web-map dependencies
+
+`cf-regions-map` loads [MapLibre GL JS 6.10.0](https://github.com/maplibre/maplibre-gl-js/tree/v6.10.0)
+(BSD-3-Clause and bundled third-party notices) from unpkg and OpenStreetMap
+tiles at runtime. OpenStreetMap attribution is displayed on the map; map data is
+available under the [Open Database License](https://www.openstreetmap.org/copyright),
+and use of the community tile service is subject to its
+[tile usage policy](https://operations.osmfoundation.org/policies/tiles/).
+Neither dependency is embedded in the region dataset. `cf-regions-gui` instead
+draws the bundled vector representations with Qt and makes no network requests.

cf_regions-0.1.0/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   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.

cf_regions-0.1.0/MANIFEST.in

@@ -0,0 +1,3 @@
+include AUTHORS.md CHANGELOG.md CODE_OF_CONDUCT.md CONTRIBUTING.md SECURITY.md
+recursive-include tools *.py
+recursive-include docs *.md

cf_regions-0.1.0/NOTICE

@@ -0,0 +1,9 @@
+cf-regions
+Copyright (C) 2026 Yves Sorge and cf-regions contributors
+
+The cf-regions source code is licensed under Apache-2.0. The bundled CF
+vocabularies and interpreted geometry catalog contain material under separate
+open-data and permissive terms. Those materials are not relicensed under
+Apache-2.0.
+See DATA_LICENSES.md for source-specific licenses, notices, attribution, and
+derivation information.