create titiler namespaces packages (#284)

* sketch * fix tests? * same version * move mosaic to its own package * move config to setup.cfg * fix bumpversion config * fix bumpversion config * update bash config * switch to . for package namespace and fix coverage * fix cov * update docs * update coverage config * Readmes * absolute links * update changelog * add python 3.9 in CI * switch to importlib.resources.files
developmentseed · Apr 19, 2021 · 6e589cf · 6e589cf
1 parent 7fbbd80
commit 6e589cf
Show file tree

Hide file tree

Showing 114 changed files with 2,247 additions and 825 deletions.
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -26,7 +26,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: [3.6, 3.7, 3.8]
+        python-version: [3.6, 3.7, 3.8, 3.9]
 
     steps:
       - uses: actions/checkout@v2
@@ -53,7 +53,7 @@ jobs:
         if: success()
         uses: codecov/codecov-action@v1
         with:
-          file: ./coverage.xml
+          files: ./coverage.xml
           flags: unittests
           name: ${{ matrix.platform }}-${{ matrix.tox-env }}
           fail_ci_if_error: false
@@ -72,7 +72,7 @@ jobs:
       - name: Install dependencies
         run: |
           python -m pip install --upgrade pip
-          python -m pip install tox
+          pip install setuptools wheel twine
 
       - name: Set tag version
         id: tag
@@ -82,15 +82,16 @@ jobs:
       - name: Set module version
         id: module
         # https://stackoverflow.com/questions/58177786/get-the-current-pushed-tag-in-github-actions
-        run: echo ::set-output name=version::$(python setup.py --version)
+        run: echo ::set-output name=version::$(python titiler/core/setup.py --version)
 
       - name: Build and publish
         if: steps.tag.outputs.tag == steps.module.outputs.version
         env:
           TOXENV: release
           TWINE_USERNAME: ${{ secrets.PYPI_USERNAME }}
           TWINE_PASSWORD: ${{ secrets.PYPI_PASSWORD }}
-        run: tox
+        run: |
+          scripts/publish
 
   publish-docker:
     needs: [tests]

diff --git a/.github/workflows/deploy_mkdocs.yml b/.github/workflows/deploy_mkdocs.yml
@@ -28,21 +28,37 @@ jobs:
       - name: Install dependencies
         run: |
           python -m pip install --upgrade pip
-          python -m pip install numpy
-          python -m pip install -e .["docs"]
-          python -m pip install git+https://github.com/timothycrosley/pdocs
+          python -m pip install titiler/core
+          python -m pip install titiler/mosaic
+          python -m pip install titiler/application
+          python -m pip install nbconvert mkdocs mkdocs-material mkdocs-jupyter pygments pdocs
 
       - name: update API docs
         run: |
           pdocs as_markdown \
-            --output_dir docs/api/ \
+            --output_dir docs/api \
             --exclude_source \
             --overwrite \
-            titiler.dependencies \
-            titiler.endpoints.factory \
-            titiler.middleware \
-            titiler.utils \
-            titiler.resources.enums
+            titiler.core.dependencies \
+            titiler.core.factory \
+            titiler.core.utils \
+            titiler.core.routing \
+            titiler.core.errors \
+            titiler.core.resources.enums
+
+          pdocs as_markdown \
+            --output_dir docs/api \
+            --exclude_source \
+            --overwrite \
+            titiler.mosaic.factory \
+            titiler.mosaic.resources.enums \
+            titiler.mosaic.errors
+
+          pdocs as_markdown \
+            --output_dir docs/api \
+            --exclude_source \
+            --overwrite \
+            titiler.application.middleware
 
       - name: Deploy docs
         run: mkdocs gh-deploy --force
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -3,42 +3,28 @@ repos:
     rev: 19.10b0
     hooks:
       - id: black
-        language_version: python3.8
-        args: ["--safe"]
+        language_version: python
 
   - repo: https://github.com/PyCQA/isort
     rev: 5.4.2
     hooks:
       - id: isort
-        language_version: python3.8
+        language_version: python
 
   - repo: https://github.com/PyCQA/flake8
     rev: 3.8.3
     hooks:
       - id: flake8
-        language_version: python3.8
-        args: [
-            # E501 let black handle all line length decisions
-            # W503 black conflicts with "line break before operator" rule
-            # E203 black conflicts with "whitespace before ':'" rule
-            "--ignore=E501,W503,E203",
-          ]
+        language_version: python
 
   - repo: https://github.com/PyCQA/pydocstyle
     rev: 5.1.1
     hooks:
       - id: pydocstyle
-        language_version: python3.8
-        args: [
-            # Check for docstring presence only
-            "--select=D1",
-            # Don't require docstrings for tests
-            '--match=(?!test).*\.py',
-          ]
+        language_version: python
 
   - repo: https://github.com/pre-commit/mirrors-mypy
-    rev: v0.770
+    rev: v0.812
     hooks:
       - id: mypy
-        language_version: python3.8
-        args: ["--no-strict-optional", "--ignore-missing-imports"]
+        language_version: python
diff --git a/CHANGES.md b/CHANGES.md
@@ -1,10 +1,50 @@
 # Release Notes
 
-## Next (TBD)
+## 0.3.0 (TBD)
 
 * add support for `.jpg` and `.jpeg` extensions (https://github.com/developmentseed/titiler/pull/271)
 * better error message when parsing the colormap value fails (https://github.com/developmentseed/titiler/pull/279)
 
+**breaking change**
+
+* split `titiler` into a set of namespaces packages (https://github.com/developmentseed/titiler/pull/284)
+
+    **titiler.core**
+
+    The `core` package host the low level tiler factories.
+    ```python
+    # before
+    from titiler.endpoints.factory import TilerFactory
+
+    # now
+    from titiler.core.factory import TilerFactory
+    ```
+
+    **titiler.mosaic**
+
+    The `mosaic` package is a plugin to `titiler.core` which adds support for MosaicJSON
+    ```python
+    # before
+    from titiler.endpoints.factory import MosaicTilerFactory
+
+    # now
+    from titiler.mosaic.factory import MosaicTilerFactory
+    ```
+
+    **titiler.application**
+
+    The `application` package is a full `ready to use` FastAPI application with support of STAC, COG and MosaicJSON.
+
+    ```bash
+    # before
+    $ pip install titiler
+    $ uvicorn titiler.main:app --reload
+
+    # now
+    $ pip install titiler.application uvicorn
+    $ uvicorn titiler.application.main:app --reload
+    ```
+
 ## 0.2.0 (2021-03-09)
 
 * adapt for cogeo-mosaic `3.0.0rc2` and add `backend_options` attribute in MosaicTilerFactory (https://github.com/developmentseed/titiler/pull/247)

diff --git a/Dockerfile b/Dockerfile
@@ -2,13 +2,14 @@ FROM tiangolo/uvicorn-gunicorn:python3.8
 
 ENV CURL_CA_BUNDLE /etc/ssl/certs/ca-certificates.crt
 
-COPY README.md /app/README.md
-COPY titiler/ /app/titiler/
-COPY setup.py /app/setup.py
+
+COPY titiler/ /tmp/titiler/
 
 # rasterio 1.2.0 wheels are built using GDAL 3.2 and PROJ 7 which we found having a
 # performance downgrade: https://github.com/developmentseed/titiler/discussions/216
-RUN pip install -e /app/. rasterio==1.1.8 --no-cache-dir
+RUN pip install /tmp/titiler/core /tmp/titiler/mosaic /tmp/titiler/application rasterio==1.1.8 --no-cache-dir
+
+RUN rm -rf /tmp/titiler
 
-ENV MODULE_NAME titiler.main
+ENV MODULE_NAME titiler.application.main
 ENV VARIABLE_NAME app
diff --git a/MANIFEST.in b/MANIFEST.in
diff --git a/README.md b/README.md
@@ -32,48 +32,53 @@
 
 ---
 
-`Titiler`, pronounced **tee-tiler** (*ti* is the diminutive version of the french *petit* which means small), is a lightweight application (FastAPI) focused on creating web map tiles dynamically from [Cloud Optimized GeoTIFF](https://cogeo.org), [STAC](https://stacspec.org) or [MosaicJSON](https://github.com/developmentseed/mosaicjson-spec/).
+`Titiler`, pronounced **tee-tiler** (*ti* is the diminutive version of the french *petit* which means small), is a set of python modules that focus on creating FastAPI application for dynamic tiling.
 
 Note: This project is the descendant of [`cogeo-tiler`](https://github.com/developmentseed/cogeo-tiler) and [`cogeo-mosaic-tiler`](https://github.com/developmentseed/cogeo-mosaic-tiler).
 
 ## Features
 
+- Built on top of [FastAPI](https://fastapi.tiangolo.com)
 - [Cloud Optimized GeoTIFF](http://www.cogeo.org/) support
 - [SpatioTemporal Asset Catalog](https://stacspec.org) support
-- Virtual mosaic support (via [MosaicJSON](https://github.com/developmentseed/mosaicjson-spec/))
-- Multiple projections (see [TileMatrixSets](https://www.ogc.org/standards/tms)) via [`morecantile`](https://github.com/developmentseed/morecantile).
+- Multiple projections support (see [TileMatrixSets](https://www.ogc.org/standards/tms)) via [`morecantile`](https://github.com/developmentseed/morecantile).
 - JPEG / JP2 / PNG / WEBP / GTIFF / NumpyTile output format support
 - OGC WMTS support
 - Automatic OpenAPI documentation (FastAPI builtin)
+- Virtual mosaic support (via [MosaicJSON](https://github.com/developmentseed/mosaicjson-spec/))
 - Example of AWS Lambda / ECS deployment (via CDK)
 
+## Packages
+
+Starting with version `0.3.0`, the `TiTiler` python module has been splitted into a set of python namespace packages: `titiler.{package}`.
+
+- [**titiler.core**](https://github.com/developmentseed/titiler/tree/master/titiler/core)
+
+    The `Core` package contains libraries to help creating dynamic tiler for COG and STAC.
+
+- [**titiler.mosaic**](https://github.com/developmentseed/titiler/tree/master/titiler/mosaic)
+
+    The `mosaic` package contains libraries to help creating dynamic tiler for MosaicJSON (adds `cogeo-mosaic` requirement).
+
+- [**titiler.application**](https://github.com/developmentseed/titiler/tree/master/titiler/application)
+
+    TiTiler's `demo` package. Contains a FastAPI application with full support of COG, STAC and MosaicJSON.
+
 ## Installation
 
 ```bash
 $ pip install -U pip
 
 # From Pypi
-$ pip install titiler
+$ pip install titiler.{package}
+# e.g
+# pip install titiler.core
+# pip install titiler.mosaic
+# pip install titiler.application
 
 # Or from sources
 $ git clone https://github.com/developmentseed/titiler.git
-$ cd titiler && pip install -e .
-```
-
-Launch Application
-```bash
-$ uvicorn titiler.main:app --reload
-```
-
-Or with Docker
-```
-$ git clone https://github.com/developmentseed/titiler.git
-$ cd titiler
-
-$ export AWS_ACCESS_KEY_ID=...
-$ export AWS_SECRET_ACCESS_KEY=...
-$ docker-compose build
-$ docker-compose up
+$ cd titiler && pip install -e titiler/core titiler/mosaic titiler/application
 ```
 
 ## Docker
@@ -100,29 +105,26 @@ docker run --name titiler \
     --rm -it public.ecr.aws/developmentseed/titiler
 ```
 
+- Built the docker locally
+```
+$ git clone https://github.com/developmentseed/titiler.git
+$ cd titiler
+
+$ export AWS_ACCESS_KEY_ID=...
+$ export AWS_SECRET_ACCESS_KEY=...
+$ docker-compose build
+$ docker-compose up
+```
+
 Some options can be set via environment variables, see: https://github.com/tiangolo/uvicorn-gunicorn-docker#advanced-usage
 
 ## Project structure
 
 ```
-titiler/                         - titiler python module.
- ├── custom/                     - Custom colormap and TMS grids.
- ├── endpoints                   - API routes.
- │   ├── cog.py                  - COG related endpoints.
- │   ├── stac.py                 - STAC related endpoints.
- │   ├── mosaic.py               - MosaicJSON related endpoints.
- │   ├── factory.py              - TiTiler Router Factories.
- │   └── tms.py                  - TileMatrixSets endpoints.
- ├── models/                     - pydantic models for this application.
- ├── resources/                  - application resources (enums, constants, etc.).
- ├── templates/                  - html/xml models.
- ├── middleware.py               - Custom Starlette middlewares.
- ├── dependencies.py             - API dependencies.
- ├── errors.py                   - API custom error handling.
- ├── main.py                     - FastAPI application creation and configuration.
- ├── settings.py                 - application configuration.
- └── utils.py                    - utility functions.
-
+titiler/                         - titiler modules.
+ ├── application/                - Titiler's `Application` package
+ ├── core/                       - Titiler's `Core` package
+ └── mosaic/                     - Titiler's `Mosaic` package
 ```
 
 ## Contribution & Development

diff --git a/mkdocs.yml b/mkdocs.yml
@@ -55,12 +55,21 @@ nav:
       - NumpyTile: "examples/notebooks/Working_with_NumpyTile.ipynb"
 
   - API:
-      - dependencies: api/titiler/dependencies.md
-      - factory: api/titiler/endpoints/factory.md
-      - middleware: api/titiler/middleware.md
-      - utils: api/titiler/utils.md
-      - enums: api/titiler/resources/enums.md
-      - errors: api/titiler/errors.md
+    - titiler.core:
+      - dependencies: api/titiler/core/dependencies.md
+      - factory: api/titiler/core/factory.md
+      - utils: api/titiler/core/utils.md
+      - routing: api/titiler/core/routing.md
+      - errors: api/titiler/core/errors.md
+      - enums: api/titiler/core/resources/enums.md
+
+    - titiler.mosaic:
+      - factory: api/titiler/mosaic/factory.md
+      - enums: api/titiler/mosaic/resources/enums.md
+      - errors: api/titiler/mosaic/errors.md
+
+    - titiler.application:
+      - middleware: api/titiler/application/middleware.md
 
   - Deployment:
     - Amazon Web Services:

diff --git a/scripts/publish b/scripts/publish
@@ -0,0 +1,17 @@
+#! /usr/bin/env bash
+
+SUBPACKAGE_DIRS=(
+    "core"
+    "mosaic"
+    "application"
+)
+
+for PACKAGE_DIR in "${SUBPACKAGE_DIRS[@]}"
+do
+    echo "publishing titiler-${PACKAGE_DIR}"
+    pushd ./titiler/${PACKAGE_DIR}
+    rm -rf dist
+    python setup.py sdist
+    # twine upload dist/*
+    popd
+done