Metadata-Version: 2.4
Name: aguirre
Version: 0.3.0
Summary: Let Python webservers self-host JS/CSS/etc assets like unpkg does
Home-page: https://github.com/pscl4rke/aguirre
Author: P. S. Clarke
Author-email: aguirre@pscl4rke.net
License: cf:licence
Project-URL: Source Code, https://github.com/pscl4rke/aguirre
Project-URL: Issues, https://github.com/pscl4rke/aguirre/issues
Project-URL: Licence, https://github.com/pscl4rke/aguirre/blob/master/LICENCE.txt
Classifier: Development Status :: 4 - Beta
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Internet :: WWW/HTTP
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENCE.txt
Provides-Extra: testing
Requires-Dist: coverage; extra == "testing"
Requires-Dist: django; extra == "testing"
Requires-Dist: django-stubs; extra == "testing"
Requires-Dist: flask; extra == "testing"
Requires-Dist: mypy; extra == "testing"
Requires-Dist: pyroma; extra == "testing"
Requires-Dist: quart; extra == "testing"
Dynamic: license-file


# Aguirre

> Let Python webservers self-host JS/CSS/etc assets like unpkg does

**Warning: The utility functions have been proven out,
but the integrations have had limited usage.
Treat them with caution.**

When your Python application needs a Python dependency from PyPI
you can lean on tools like `pip` and `venv` to manage that.
But what if its a web application that needs a Javascript or
CSS dependency from NPM?
Large applications run by large teams can justify elaborate
build and deployment pipelines.
But a smaller app?
Something internal?
A demo?
Or a learning exercise?
You want a lighter solution...

In recent years it's become popular to lean on unpkg for this.
(Or jsdelivr, or cdnjs, or another service.)
How easy it is to drop one line into your template and let a CDN
look after serving the file to your users:

    <script src="https://www.unpkg.com/jquery@3.7.1/dist/jquery.min.js"></script>

But there are disadvantages to relying on a third party like this.
It needs to be up whenever your app is up, and be reliable.
You are vulnerable to takedowns (remember left-pad?).
Your users give up more privacy.
And worst of all: you can't develop your application offline.

Aguirre lets you download NPM tarballs and add them to your app.
(And probably commit them in too.)
Then you can drop a line into your app and let Aguirre serve the
desired file straight out of the tarball:

    <script src="/pkgs/jquery@3.7.1/dist/jquery.min.js"></script>

Sure, it's not the most scalable solution.
But it's a great way to quickly get things moving.
And if you have a frontend (edge) server configured to do
caching you may find it can handle the scaling for you!

## Installation

This code is not currently on PyPI.
Consequently you should add the following line to your
`requirements.txt` file:

    git+https://github.com/pscl4rke/aguirre.git

## Integrations

There are some integrations into frameworks inside
`aguirre.integrations`.
Their usage is documented in the module docstrings...

* [Flask](https://github.com/pscl4rke/aguirre/blob/master/aguirre/integrations/flask.py)
* [Quart](https://github.com/pscl4rke/aguirre/blob/master/aguirre/integrations/quart.py)
* [Django](https://github.com/pscl4rke/aguirre/blob/master/aguirre/integrations/django.py) (Partial!)

## Development and Testing

This codebase uses
[ephemerun](https://github.com/pscl4rke/ephemerun)
to test against multiple Python versions.
(It's a bit like Tox,
except is uses containers for isolation rather than virtualenvs.)

## Roadmap

* Better Django support
* Handle `pathlib.Path` arguments
* Prove the headers etc for caching middleware/frontends
* Make sure no `Set-Cookie` headers exist to stop caching proxies

## Licence

This code is copyright P. S. Clarke and is licensed under
the BSD-3-Clause licence.

The test suite contains real-world example files.
These are covered by their own embedded licences.
