plain 0.1.0__tar.gz

plain-0.1.0/LICENSE

@@ -0,0 +1,85 @@
+## Plain is released under the BSD 3-Clause License
+
+BSD 3-Clause License
+
+Copyright (c) 2023, Dropseed, LLC
+
+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.
+
+
+## This package contains code forked from github.com/django/django
+
+Copyright (c) Django Software Foundation and individual contributors.
+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 Django 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 OWNER 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.
+
+
+## This package contains code forked from github.com/evansd/whitenoise
+
+The MIT License (MIT)
+
+Copyright (c) 2013 David Evans
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

plain-0.1.0/PKG-INFO

@@ -0,0 +1,51 @@
+Metadata-Version: 2.1
+Name: plain
+Version: 0.1.0
+Summary: A web framework for building products with Python.
+Author: Dave Gaeddert
+Author-email: dave.gaeddert@dropseed.dev
+Requires-Python: >=3.11,<4.0
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Dist: click (>=8.0.0)
+Requires-Dist: jinja2 (>=3.1.2,<4.0.0)
+Requires-Dist: python-dotenv (>=1.0.0,<2.0.0)
+Description-Content-Type: text/markdown
+
+<!-- This file is compiled from plain/plain/README.md. Do not edit this file directly. -->
+
+# Plain
+
+Plain is a web framework for building products with Python.
+
+With the core `plain` package you can build an app that:
+
+- Matches [URL patterns](https://plainframework.com/docs/plain/plain/urls) to Python [views](https://plainframework.com/docs/plain/plain/views)
+- Handles [HTTP requests and responses](https://plainframework.com/docs/plain/plain/http)
+- Renders [HTML templates](https://plainframework.com/docs/plain/plain/templates) with Jinja
+- Processes user input via [forms](https://plainframework.com/docs/plain/plain/forms)
+- Has a [CLI interface](https://plainframework.com/docs/plain/plain/cli)
+- Serves static [assets](https://plainframework.com/docs/plain/plain/assets) (CSS, JS, images)
+- Can be modified with [middleware](https://plainframework.com/docs/plain/plain/middleware)
+- Integrates first-party and third-party [packages](https://plainframework.com/docs/plain/plain/packages)
+- Has a [preflight check system](https://plainframework.com/docs/plain/plain/preflight)
+
+With the official Plain ecosystem packages you can:
+
+- Integrate a full-featured [database ORM](https://plainframework.com/docs/plain-models/)
+- Use a built-in [user authentication](https://plainframework.com/docs/plain-auth/) system
+- [Lint and format code](https://plainframework.com/docs/plain-code/)
+- Run a [database-backed cache](https://plainframework.com/docs/plain-cache/)
+- [Send emails](https://plainframework.com/docs/plain-mail/)
+- Streamline [local development](https://plainframework.com/docs/plain-dev/)
+- Manage [feature flags](https://plainframework.com/docs/plain-flags/)
+- Integrate [HTMX](https://plainframework.com/docs/plain-htmx/)
+- Style with [Tailwind CSS](https://plainframework.com/docs/plain-tailwind/)
+- Add [OAuth login](https://plainframework.com/docs/plain-oauth/) and API access
+- Run tests with [pytest](https://plainframework.com/docs/plain-test/)
+- Run a [background job worker](https://plainframework.com/docs/plain-worker/)
+- Build [staff tooling and admin dashboards](https://plainframework.com/docs/plain-staff/)
+
+Learn more at [plainframework.com](https://plainframework.com).
+

plain-0.1.0/README.md

@@ -0,0 +1,35 @@
+<!-- This file is compiled from plain/plain/README.md. Do not edit this file directly. -->
+
+# Plain
+
+Plain is a web framework for building products with Python.
+
+With the core `plain` package you can build an app that:
+
+- Matches [URL patterns](https://plainframework.com/docs/plain/plain/urls) to Python [views](https://plainframework.com/docs/plain/plain/views)
+- Handles [HTTP requests and responses](https://plainframework.com/docs/plain/plain/http)
+- Renders [HTML templates](https://plainframework.com/docs/plain/plain/templates) with Jinja
+- Processes user input via [forms](https://plainframework.com/docs/plain/plain/forms)
+- Has a [CLI interface](https://plainframework.com/docs/plain/plain/cli)
+- Serves static [assets](https://plainframework.com/docs/plain/plain/assets) (CSS, JS, images)
+- Can be modified with [middleware](https://plainframework.com/docs/plain/plain/middleware)
+- Integrates first-party and third-party [packages](https://plainframework.com/docs/plain/plain/packages)
+- Has a [preflight check system](https://plainframework.com/docs/plain/plain/preflight)
+
+With the official Plain ecosystem packages you can:
+
+- Integrate a full-featured [database ORM](https://plainframework.com/docs/plain-models/)
+- Use a built-in [user authentication](https://plainframework.com/docs/plain-auth/) system
+- [Lint and format code](https://plainframework.com/docs/plain-code/)
+- Run a [database-backed cache](https://plainframework.com/docs/plain-cache/)
+- [Send emails](https://plainframework.com/docs/plain-mail/)
+- Streamline [local development](https://plainframework.com/docs/plain-dev/)
+- Manage [feature flags](https://plainframework.com/docs/plain-flags/)
+- Integrate [HTMX](https://plainframework.com/docs/plain-htmx/)
+- Style with [Tailwind CSS](https://plainframework.com/docs/plain-tailwind/)
+- Add [OAuth login](https://plainframework.com/docs/plain-oauth/) and API access
+- Run tests with [pytest](https://plainframework.com/docs/plain-test/)
+- Run a [background job worker](https://plainframework.com/docs/plain-worker/)
+- Build [staff tooling and admin dashboards](https://plainframework.com/docs/plain-staff/)
+
+Learn more at [plainframework.com](https://plainframework.com).

plain-0.1.0/plain/README.md

@@ -0,0 +1,33 @@
+# Plain
+
+Plain is a web framework for building products with Python.
+
+With the core `plain` package you can build an app that:
+
+- Matches [URL patterns](./urls) to Python [views](./views)
+- Handles [HTTP requests and responses](./http)
+- Renders [HTML templates](./templates) with Jinja
+- Processes user input via [forms](./forms)
+- Has a [CLI interface](./cli)
+- Serves static [assets](./assets) (CSS, JS, images)
+- Can be modified with [middleware](./middleware)
+- Integrates first-party and third-party [packages](./packages)
+- Has a [preflight check system](./preflight)
+
+With the official Plain ecosystem packages you can:
+
+- Integrate a full-featured [database ORM](https://plainframework.com/docs/plain-models/)
+- Use a built-in [user authentication](https://plainframework.com/docs/plain-auth/) system
+- [Lint and format code](https://plainframework.com/docs/plain-code/)
+- Run a [database-backed cache](https://plainframework.com/docs/plain-cache/)
+- [Send emails](https://plainframework.com/docs/plain-mail/)
+- Streamline [local development](https://plainframework.com/docs/plain-dev/)
+- Manage [feature flags](https://plainframework.com/docs/plain-flags/)
+- Integrate [HTMX](https://plainframework.com/docs/plain-htmx/)
+- Style with [Tailwind CSS](https://plainframework.com/docs/plain-tailwind/)
+- Add [OAuth login](https://plainframework.com/docs/plain-oauth/) and API access
+- Run tests with [pytest](https://plainframework.com/docs/plain-test/)
+- Run a [background job worker](https://plainframework.com/docs/plain-worker/)
+- Build [staff tooling and admin dashboards](https://plainframework.com/docs/plain-staff/)
+
+Learn more at [plainframework.com](https://plainframework.com).

plain-0.1.0/plain/__main__.py

@@ -0,0 +1,5 @@
+from .cli import cli
+
+# Make the CLI available as `python -m plain`
+if __name__ == "__main__":
+    cli()

plain-0.1.0/plain/assets/README.md

@@ -0,0 +1,56 @@
+# Assets
+
+Serve static assets (CSS, JS, images, etc.) for your app.
+
+The default behavior is for Plain to serve assets directly via a middleware.
+This is based on [whitenoise](http://whitenoise.evans.io/en/stable/).
+
+## Usage
+
+Generally speaking, the simplest way to include assests in your app is to put them either in `app/assets` or `app/<package>/assets`.
+
+Then in your template you can use the `asset()` function to get the URL.
+
+```html
+<link rel="stylesheet" href="{{ asset('css/style.css') }}">
+```
+
+If you ever need to reference an asset directly in Python code, you can use the `get_asset_url()` function.
+
+```python
+from plain.assets import get_asset_url
+
+print(get_asset_url("css/style.css"))
+```
+
+## Settings
+
+These are the default settings related to assets handling.
+
+```python
+# app/settings.py
+MIDDLEWARE = [
+    "plain.middleware.security.SecurityMiddleware",
+    "plain.assets.whitenoise.middleware.WhiteNoiseMiddleware",  # <--
+    "plain.middleware.common.CommonMiddleware",
+    "plain.csrf.middleware.CsrfViewMiddleware",
+    "plain.middleware.clickjacking.XFrameOptionsMiddleware",
+]
+
+ASSETS_BACKEND = "plain.assets.whitenoise.storage.CompressedManifestStaticFilesStorage"
+
+# List of finder classes that know how to find assets files in
+# various locations.
+ASSETS_FINDERS = [
+    "plain.assets.finders.FileSystemFinder",
+    "plain.assets.finders.PackageDirectoriesFinder",
+]
+
+# Absolute path to the directory assets files should be collected to.
+# Example: "/var/www/example.com/assets/"
+ASSETS_ROOT = PLAIN_TEMP_PATH / "assets_collected"
+
+# URL that handles the assets files served from ASSETS_ROOT.
+# Example: "http://example.com/assets/", "http://assets.example.com/"
+ASSETS_URL = "/assets/"
+```

plain-0.1.0/plain/assets/__init__.py

@@ -0,0 +1,6 @@
+from . import preflight  # noqa
+from .storage import assets_storage
+
+
+def get_asset_url(path):
+    return assets_storage.url(path)

plain-0.1.0/plain/assets/finders.py

@@ -0,0 +1,233 @@
+import functools
+import os
+
+from plain.assets import utils
+from plain.assets.storage import FileSystemStorage
+from plain.exceptions import ImproperlyConfigured
+from plain.packages import packages
+from plain.runtime import APP_PATH
+from plain.utils._os import safe_join
+from plain.utils.module_loading import import_string
+
+# To keep track on which directories the finder has searched the static files.
+searched_locations = []
+
+
+APP_ASSETS_DIR = APP_PATH / "assets"
+
+
+class BaseFinder:
+    """
+    A base file finder to be used for custom assets finder classes.
+    """
+
+    def check(self, **kwargs):
+        raise NotImplementedError(
+            "subclasses may provide a check() method to verify the finder is "
+            "configured correctly."
+        )
+
+    def find(self, path, all=False):
+        """
+        Given a relative file path, find an absolute file path.
+
+        If the ``all`` parameter is False (default) return only the first found
+        file path; if True, return a list of all found files paths.
+        """
+        raise NotImplementedError(
+            "subclasses of BaseFinder must provide a find() method"
+        )
+
+    def list(self, ignore_patterns):
+        """
+        Given an optional list of paths to ignore, return a two item iterable
+        consisting of the relative path and storage instance.
+        """
+        raise NotImplementedError(
+            "subclasses of BaseFinder must provide a list() method"
+        )
+
+
+class FileSystemFinder(BaseFinder):
+    """
+    A static files finder that looks in "static"
+    """
+
+    def __init__(self, package_names=None, *args, **kwargs):
+        # List of locations with static files
+        self.locations = []
+        # Maps dir paths to an appropriate storage instance
+        self.storages = {}
+
+        root = APP_ASSETS_DIR
+
+        if isinstance(root, list | tuple):
+            prefix, root = root
+        else:
+            prefix = ""
+        if (prefix, root) not in self.locations:
+            self.locations.append((prefix, root))
+        for prefix, root in self.locations:
+            filesystem_storage = FileSystemStorage(location=root)
+            filesystem_storage.prefix = prefix
+            self.storages[root] = filesystem_storage
+        super().__init__(*args, **kwargs)
+
+    # def check(self, **kwargs):
+    #     errors = []
+    #     if settings.ASSETS_ROOT and os.path.abspath(
+    #         settings.ASSETS_ROOT
+    #     ) == os.path.abspath(self.path):
+    #         errors.append(
+    #             Error(
+    #                 "The STATICFILES_DIR setting should not contain the "
+    #                 "ASSETS_ROOT setting.",
+    #                 id="assets.E002",
+    #             )
+    #         )
+    #     return errors
+
+    def find(self, path, all=False):
+        matches = []
+        for prefix, root in self.locations:
+            if root not in searched_locations:
+                searched_locations.append(root)
+            matched_path = self.find_location(root, path, prefix)
+            if matched_path:
+                if not all:
+                    return matched_path
+                matches.append(matched_path)
+        return matches
+
+    def find_location(self, root, path, prefix=None):
+        """
+        Find a requested static file in a location and return the found
+        absolute path (or ``None`` if no match).
+        """
+        if prefix:
+            prefix = f"{prefix}{os.sep}"
+            if not path.startswith(prefix):
+                return None
+            path = path.removeprefix(prefix)
+        path = safe_join(root, path)
+        if os.path.exists(path):
+            return path
+
+    def list(self, ignore_patterns):
+        """
+        List all files in all locations.
+        """
+        for prefix, root in self.locations:
+            # Skip nonexistent directories.
+            if os.path.isdir(root):
+                storage = self.storages[root]
+                for path in utils.get_files(storage, ignore_patterns):
+                    yield path, storage
+
+
+class PackageDirectoriesFinder(BaseFinder):
+    """
+    A static files finder that looks in the directory of each app as
+    specified in the source_dir attribute.
+    """
+
+    storage_class = FileSystemStorage
+    source_dir = "assets"
+
+    def __init__(self, package_names=None, *args, **kwargs):
+        # The list of packages that are handled
+        self.packages = []
+        # Mapping of app names to storage instances
+        self.storages = {}
+        package_configs = packages.get_package_configs()
+        if package_names:
+            package_names = set(package_names)
+            package_configs = [ac for ac in package_configs if ac.name in package_names]
+        for package_config in package_configs:
+            app_storage = self.storage_class(
+                os.path.join(package_config.path, self.source_dir)
+            )
+            if os.path.isdir(app_storage.location):
+                self.storages[package_config.name] = app_storage
+                if package_config.name not in self.packages:
+                    self.packages.append(package_config.name)
+        super().__init__(*args, **kwargs)
+
+    def list(self, ignore_patterns):
+        """
+        List all files in all app storages.
+        """
+        for storage in self.storages.values():
+            if storage.exists(""):  # check if storage location exists
+                for path in utils.get_files(storage, ignore_patterns):
+                    yield path, storage
+
+    def find(self, path, all=False):
+        """
+        Look for files in the app directories.
+        """
+        matches = []
+        for app in self.packages:
+            app_location = self.storages[app].location
+            if app_location not in searched_locations:
+                searched_locations.append(app_location)
+            match = self.find_in_app(app, path)
+            if match:
+                if not all:
+                    return match
+                matches.append(match)
+        return matches
+
+    def find_in_app(self, app, path):
+        """
+        Find a requested static file in an app's static locations.
+        """
+        storage = self.storages.get(app)
+        # Only try to find a file if the source dir actually exists.
+        if storage and storage.exists(path):
+            matched_path = storage.path(path)
+            if matched_path:
+                return matched_path
+
+
+def find(path, all=False):
+    """
+    Find a static file with the given path using all enabled finders.
+
+    If ``all`` is ``False`` (default), return the first matching
+    absolute path (or ``None`` if no match). Otherwise return a list.
+    """
+    searched_locations[:] = []
+    matches = []
+    for finder in get_finders():
+        result = finder.find(path, all=all)
+        if not all and result:
+            return result
+        if not isinstance(result, list | tuple):
+            result = [result]
+        matches.extend(result)
+    if matches:
+        return matches
+    # No match.
+    return [] if all else None
+
+
+def get_finders():
+    from plain.runtime import settings
+
+    for finder_path in settings.ASSETS_FINDERS:
+        yield get_finder(finder_path)
+
+
+@functools.cache
+def get_finder(import_path):
+    """
+    Import the assets finder class described by import_path, where
+    import_path is the full Python path to the class.
+    """
+    Finder = import_string(import_path)
+    if not issubclass(Finder, BaseFinder):
+        raise ImproperlyConfigured(
+            f'Finder "{Finder}" is not a subclass of "{BaseFinder}"'
+        )
+    return Finder()

plain-0.1.0/plain/assets/preflight.py

@@ -0,0 +1,14 @@
+from plain.assets.finders import get_finders
+
+
+def check_finders(package_configs=None, **kwargs):
+    """Check all registered assets finders."""
+    errors = []
+    for finder in get_finders():
+        try:
+            finder_errors = finder.check()
+        except NotImplementedError:
+            pass
+        else:
+            errors.extend(finder_errors)
+    return errors