What's a Namespace Package? (#354)

* namespace packages hello world

* snake shop idea + fake data generation

* adding README

* renaming to snake-corp

* adding namespace plugins and @gahjelle prototype

* experimenting with plugins

* data-repo v2, snake business cleanup, plugins example

* adding to business example

* using both packages in business demo

* updates while writing article

* fixing import

* TR updates

* Corporation instead of corp

* @gahjelle TR fixes

* Adding *a* s to docstrings

* README LE

* rename repo to repos

* typo fix

* Final QA tweaks

* Lint

---------

Co-authored-by: KateFinegan <[email protected]>
Co-authored-by: Geir Arne Hjelle <[email protected]>

Author: 3 people

Diff for: namespace-package/README.md

@@ -0,0 +1,32 @@
+# What's a Python Namespace Package, and What's It For?
+
+Materials for the corresponding Real Python tutorial, [What's a Python Namespace Package, and What's It For?](https://realpython.com/python-namespace-package/).
+
+You have the source code for the Snake Corporation example that's hosted on PyPI. Aditionally, as an extra, you have the code to generate the fake data used.
+
+You need to install every subpackage to get the code working properly.
+
+## Examples
+
+In this repository, you'll find three different examples showing ways that namespace packages work or can be used.
+
+### Business
+
+A typical use case of namespace packages is for large businesses that want to make sure all their code is packaged under a namespace. In this and subsequent examples, you play the role of the fictional Snake Corporation.
+
+For this example, the Snake Corporation has two separate utility packages, but when both are installed, both are available under the same `snake_corp` namespace:
+
+```py
+>>> from snake_corp import dateutil
+>>> from snake_corp import magic
+```
+
+### Distributed Data Repository
+
+In this example, you make a namespace package that serves as a wrapper around your data files. This allows you to create separate packages that only contain data.
+
+This way, an organization like Real Python can have some core functionality in the main package, like the functions to read the data, and then have many satellite data packages that just include a particular dataset and insert it into the namespace so it can be read by the core package.
+
+### Plugin System
+
+In this example, you take the data repository example further by adding a plugin system for the readers so that you can support your own custom formats. 

Diff for: namespace-package/business/pyproject.toml

@@ -0,0 +1,2 @@
+[tool.black]
+line-length=79

Diff for: namespace-package/business/snake-corp-dateutil/pyproject.toml

@@ -0,0 +1,14 @@
+[build-system]
+requires      = ["setuptools", "setuptools-scm"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+where      = ["."]
+include    = ["snake_corp"]
+namespaces = true
+
+[project]
+name        = "snake-corp-dateutil"
+version     = "1.0.3"
+description = "Date Utilities for the Snake Corporation"
+license     = { text = "Snake Corp Software License Agreement" }

Diff for: namespace-package/business/snake-corp-dateutil/snake_corp/dateutil.py

@@ -0,0 +1,12 @@
+from datetime import datetime
+
+
+def days_to_snake_day(from_date=None):
+    """Return the number of days until World Snake Day (July 16th)."""
+    if from_date is None:
+        from_date = datetime.now()
+    if from_date.month > 7 or (from_date.month == 7 and from_date.day > 16):
+        day_of_snake = datetime(from_date.year + 1, 7, 16)
+    else:
+        day_of_snake = datetime(from_date.year, 7, 16)
+    return (day_of_snake - from_date).days

Diff for: namespace-package/business/snake-corp-magic-numbers/pyproject.toml

@@ -0,0 +1,14 @@
+[build-system]
+requires      = ["setuptools", "setuptools-scm"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+where      = ["."]
+include    = ["snake_corp"]
+namespaces = true
+
+[project]
+name        = "snake-corp-magic-numbers"
+version     = "1.1.8"
+description = "Super Magic Secret Numbers for the Snake Corporation"
+license     = { text = "Snake Corp Software License Agreement" }

Diff for: namespace-package/business/snake-corp-magic-numbers/snake_corp/magic.py

@@ -0,0 +1,6 @@
+import random
+
+
+def secret_number_generator():
+    # Insert special Snake Corporation sauce here ...
+    return random.randint(0, 9999)

Diff for: namespace-package/business/snake-service/snake_service.py

@@ -0,0 +1,4 @@
+from snake_corp import dateutil, magic
+
+print(magic.secret_number_generator())
+print(dateutil.days_to_snake_day())

Diff for: namespace-package/data-repos-demo/README.md

@@ -0,0 +1,13 @@
+```s
+$ python -m venv venv
+$ source venv/bin/activate
+(venv) $ python -m pip install -e data-repos/
+(venv) $ python -m pip install -e snake-corp-product-data/
+```
+
+```powershell
+PS> python -m venv venv
+PS> venv\scripts\activate
+(venv) PS> python -m pip install -e "data-repos\"
+(venv) PS> python -m pip install -e "snake-corp-product-data\"
+```

Diff for: namespace-package/data-repos-demo/client-service/process_products.py

@@ -0,0 +1,3 @@
+from data_repos import read
+
+read.data("products")

Diff for: namespace-package/data-repos-demo/data-repos/data_repos/read.py

@@ -0,0 +1,31 @@
+from importlib import resources
+
+import pandas as pd
+
+
+def data(name):
+    """Get a data file."""
+    data_path = path(name)
+    file_type = data_path.suffix.lstrip(".")
+    return readers[file_type](data_path)
+
+
+def path(name):
+    """Find the path to a data file."""
+    for resource in resources.files(__package__).iterdir():
+        if resource.stem == name:
+            return resource
+    raise FileNotFoundError(f"{name} not found in {__package__}")
+
+
+def csv(data_path):
+    """Read a CSV file from a path."""
+    return pd.read_csv(data_path)
+
+
+def json(data_path):
+    """Read a JSON file from a path."""
+    return pd.read_json(data_path)
+
+
+readers = {"csv": csv, "json": json}

Diff for: namespace-package/data-repos-demo/data-repos/pyproject.toml

@@ -0,0 +1,23 @@
+[build-system]
+requires      = ["setuptools", "setuptools-scm"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+where      = ["."]
+include    = ["data_repos"]
+namespaces = true
+
+[project]
+name = "data-repos"
+version = "1.0.0"
+authors = [
+    { name = "Ian Currie", email = "[email protected]" },
+    { name = "Geir Arne Hjelle", email = "[email protected]" },
+]
+description = "A namespace provider for distributed data repositories"
+readme = "README.md"
+requires-python = ">=3.7"
+keywords = ["namespace", "data"]
+license = { text = "MIT" }
+classifiers = ["Programming Language :: Python :: 3"]
+dependencies = ["pandas"]