Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/florimondmanca/asgi-sitemaps
Sitemap generation for Python ASGI web apps
https://github.com/florimondmanca/asgi-sitemaps
asgi async fastapi python sitemap-generator starlette
Last synced: 12 days ago
JSON representation
Sitemap generation for Python ASGI web apps
- Host: GitHub
- URL: https://github.com/florimondmanca/asgi-sitemaps
- Owner: florimondmanca
- License: mit
- Created: 2020-05-31T15:38:57.000Z (over 4 years ago)
- Default Branch: master
- Last Pushed: 2024-03-20T16:22:18.000Z (10 months ago)
- Last Synced: 2024-05-02T05:07:52.150Z (9 months ago)
- Topics: asgi, async, fastapi, python, sitemap-generator, starlette
- Language: Python
- Homepage: https://pypi.org/project/asgi-sitemaps/
- Size: 51.8 KB
- Stars: 21
- Watchers: 2
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
- awesome-fastapi - :octocat: asgi-sitemaps :star: 10+ :fork_and_knife: 0+ - Sitemap generation for Python ASGI web apps. (Async)
README
# asgi-sitemaps
[](https://dev.azure.com/florimondmanca/public/_build/latest?definitionId=11&branchName=master)
[](https://codecov.io/gh/florimondmanca/asgi-sitemaps)
[](https://pypi.org/project/asgi-sitemaps)
[Sitemap](https://www.sitemaps.org) generation for ASGI applications. Inspired by [Django's sitemap framework](https://docs.djangoproject.com/en/3.0/ref/contrib/sitemaps/).
**Contents**
- [Features](#features)
- [Installation](#installation)
- [Quickstart](#quickstart)
- [How-To](#how-to)
- [Sitemap sections](#sitemap-sections)
- [Dynamic generation from database queries](#dynamic-generation-from-database-queries)
- [Advanced web framework integration](#advanced-web-framework-integration)
- [API Reference](#api-reference)
- [`Sitemap`](#class-sitemap)
- [`SitemapApp`](#class-sitemapapp)
## Features
- Build and compose sitemap sections into a single dynamic ASGI endpoint.
- Supports drawing sitemap items from a variety of sources (static lists, (async) ORM queries, etc).
- Compatible with any ASGI framework.
- Fully type annotated.
- 100% test coverage.
## Installation
Install with pip:
```shell
$ pip install 'asgi-sitemaps==1.*'
```
`asgi-sitemaps` requires Python 3.7+.
## Quickstart
Let's build a static sitemap for a "Hello, world!" application. The sitemap will contain a single URL entry for the home `/` endpoint.
Here is the project file structure:
```console
.
└── server
├── __init__.py
├── app.py
└── sitemap.py
```
First, declare a sitemap section by subclassing `Sitemap`, then wrap it in a `SitemapApp`:
```python
# server/sitemap.py
import asgi_sitemaps
class Sitemap(asgi_sitemaps.Sitemap):
def items(self):
return ["/"]
def location(self, item: str):
return item
def changefreq(self, item: str):
return "monthly"
sitemap = asgi_sitemaps.SitemapApp(Sitemap(), domain="example.io")
```
Now, register the `sitemap` endpoint as a route onto your ASGI app. For example, if using Starlette:
```python
# server/app.py
from starlette.applications import Starlette
from starlette.responses import PlainTextResponse
from starlette.routing import Route
from .sitemap import sitemap
async def home(request):
return PlainTextResponse("Hello, world!")
routes = [
Route("/", home),
Route("/sitemap.xml", sitemap),
]
app = Starlette(routes=routes)
```
Serve the app using `$ uvicorn server.app:app`, then request the sitemap:
```bash
curl http://localhost:8000/sitemap.xml
```
```xml
http://example.io/
monthly
0.5
```
Tada!
To learn more:
- See [How-To](#how-to) for more advanced usage, including splitting the sitemap in multiple sections, and dynamically generating entries from database queries.
- See the [`Sitemap` API reference](#class-sitemap) for all supported sitemap options.
## How-To
### Sitemap sections
You can combine multiple sitemap classes into a single sitemap endpoint. This is useful to split the sitemap in multiple sections that may have different `items()` and/or sitemap attributes. Such sections could be static pages, blog posts, recent articles, etc.
To do so, declare multiple sitemap classes, then pass them as a list to `SitemapApp`:
```python
# server/sitemap.py
import asgi_sitemaps
class StaticSitemap(asgi_sitemaps.Sitemap):
...
class BlogSitemap(asgi_sitemaps.Sitemap):
...
sitemap = asgi_sitemaps.SitemapApp([StaticSitemap(), BlogSitemap()], domain="example.io")
```
Entries from each sitemap will be concatenated when building the final `sitemap.xml`.
### Dynamic generation from database queries
`Sitemap.items()` supports consuming any async iterable. This means you can easily integrate with an async database client or ORM so that `Sitemap.items()` fetches and returns relevant rows for generating your sitemap.
Here's an example using [Databases](https://github.com/encode/databases), assuming you have a `Database` instance in `server/resources.py`:
```python
# server/sitemap.py
import asgi_sitemaps
from .resources import database
class Sitemap(asgi_sitemaps.Sitemap):
async def items(self):
query = "SELECT permalink, updated_at FROM articles;"
return await database.fetch_all(query)
def location(self, row: dict):
return row["permalink"]
```
### Advanced web framework integration
While `asgi-sitemaps` is framework-agnostic, you can use the [`.scope` attribute](#scope) available on `Sitemap` instances to feed the ASGI scope into your framework-specific APIs for inspecting and manipulating request information.
Here is an example with [Starlette](https://www.starlette.io) where we build sitemap of static pages. To decouple from the raw URL paths, pages are referred to by view name. We reverse-lookup their URLs by building a `Request` instance from the ASGI `.scope`, and using `.url_for()`:
```python
# server/sitemap.py
import asgi_sitemaps
from starlette.datastructures import URL
from starlette.requests import Request
class StaticSitemap(asgi_sitemaps.Sitemap):
def items(self):
return ["home", "about", "blog:home"]
def location(self, name: str):
request = Request(scope=self.scope)
url = request.url_for(name)
return URL(url).path
```
The corresponding Starlette routing table could look something like this:
```python
# server/routes.py
from starlette.routing import Mount, Route
from . import views
from .sitemap import sitemap
routes = [
Route("/", views.home, name="home"),
Route("/about", views.about, name="about"),
Route("/blog/", views.blog_home, name="blog:home"),
Route("/sitemap.xml", sitemap),
]
```
## API Reference
### _class_ `Sitemap`
Represents a source of sitemap entries.
You can specify the type `T` of sitemap items for extra type safety:
```python
import asgi_sitemaps
class MySitemap(asgi_sitemaps.Sitemap[str]):
...
```
#### _async_ `items`
Signature: `async def () -> Union[Iterable[T], AsyncIterable[T]]`
_(**Required**)_ Return an [iterable](https://docs.python.org/3/glossary.html#term-iterable) or an [asynchronous iterable](https://docs.python.org/3/glossary.html#term-asynchronous-iterable) of items of the same type. Each item will be passed as-is to `.location()`, `.lastmod()`, `.changefreq()`, and `.priority()`.
Examples:
```python
# Simplest usage: return a list
def items(self) -> List[str]:
return ["/", "/contact"]
# Async operations are also supported
async def items(self) -> List[dict]:
query = "SELECT permalink, updated_at FROM pages;"
return await database.fetch_all(query)
# Sync and async generators are also supported
async def items(self) -> AsyncIterator[dict]:
query = "SELECT permalink, updated_at FROM pages;"
async for row in database.aiter_rows(query):
yield row
```
#### `location`
Signature: `def (item: T) -> str`
_(**Required**)_ Return the absolute path of a sitemap item.
"Absolute path" means an URL path without a protocol or domain. For example: `/blog/my-article`. (So `https://mydomain.com/blog/my-article` is not a valid location, nor is `mydomain.com/blog/my-article`.)
#### `lastmod`
Signature: `def (item: T) -> Optional[datetime.datetime]`
_(Optional)_ Return the [date of last modification](https://www.sitemaps.org/protocol.html#lastmoddef) of a sitemap item as a [`datetime`](https://docs.python.org/3/library/datetime.html#datetime.datetime) object, or `None` (the default) for no `lastmod` field.
#### `changefreq`
Signature: `def (item: T) -> Optional[str]`
_(Optional)_ Return the [change frequency](https://www.sitemaps.org/protocol.html#changefreqdef) of a sitemap item.
Possible values are:
- `None` - No `changefreq` field (the default).
- `"always"`
- `"hourly"`
- `"daily"`
- `"weekly"`
- `"monthly"`
- `"yearly"`
- `"never"`
#### `priority`
Signature: `def (item: T) -> float`
_(Optional)_ Return the [priority](https://www.sitemaps.org/protocol.html#prioritydef) of a sitemap item. Must be between 0 and 1. Defaults to `0.5`.
#### `protocol`
Type: `str`
_(Optional)_ This attribute defines the protocol used to build URLs of the sitemap.
Possible values are:
- `"auto"` - The protocol with which the sitemap was requested (the default).
- `"http"`
- `"https"`
#### `scope`
This property returns the [ASGI scope](https://asgi.readthedocs.io/en/latest/specs/www.html#connection-scope) of the current HTTP request.
### _class_ `SitemapApp`
An ASGI application that responds to HTTP requests with the `sitemap.xml` contents of the sitemap.
Parameters:
- _(**Required**)_ `sitemaps` - A `Sitemap` object or a list of `Sitemap` objects, used to generate sitemap entries.
- _(**Required**)_ `domain` - The domain to use when generating sitemap URLs.
Examples:
```python
sitemap = SitemapApp(Sitemap(), domain="mydomain.com")
sitemap = SitemapApp([StaticSitemap(), BlogSitemap()], domain="mydomain.com")
```
## License
MIT