sitemapr 0.1.0__tar.gz

sitemapr-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Seonu Jang
+
+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.

sitemapr-0.1.0/PKG-INFO

@@ -0,0 +1,84 @@
+Metadata-Version: 2.1
+Name: sitemapr
+Version: 0.1.0
+Summary: sitemapr is a library that generates sitemaps for SPA websites with declaritve configuration in Python.
+License: MIT
+Author: sjquant
+Author-email: seonujang92@gmail.com
+Requires-Python: >=3.11,<4.0
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Dist: pydantic (>=2.6.3,<3.0.0)
+Requires-Dist: typer (>=0.9.0,<0.10.0)
+Description-Content-Type: text/markdown
+
+# sitemapr
+
+`sitemapr` is a Python library designed to generate and save sitemaps for websites. It allows for the creation of detailed sitemaps with customizable parameters, making it easier for search engines to crawl and index web pages efficiently.
+
+## Features
+
+- Generate sitemaps with dynamic URL parameters.
+- Split large sitemaps into chunks to comply with sitemap index specifications.
+- Customizable base URLs for sitemaps and websites.
+
+## Installation
+
+SiteMapr can be easily installed using pip. Ensure you have pip installed and run the following command:
+
+```sh
+pip install sitemapr
+```
+
+This command will download and install SiteMapr along with its dependencies.
+
+## Quick Start
+
+Here's how to quickly generate a sitemap for your website using SiteMapr:
+
+1. **Define Your Pages**: First, define the pages you want to include in your sitemap, including any dynamic path or query parameters.
+
+2. **Create a SiteMapr Instance**: Initialize SiteMapr with your website's base URL and the pages you've defined.
+
+3. **Save Your Sitemap**: Choose a directory and save your sitemap, specifying chunk sizes if needed.
+
+### Example
+
+```python
+from sitemapr import Page, Param, SiteMapr
+
+# Define the pages of your site
+pages = [
+    Page(
+        path="",
+        query_params=[
+            Param(name="page", values=["home", "about", "contact"]),
+            Param(name="sort", values=["asc", "desc"]),
+        ],
+    ),
+    Page(
+        path="/blog",
+        query_params=[
+            Param(name="page", values=["1", "2", "3"]),
+            Param(name="sort", values=["asc", "desc"]),
+        ],
+    ),
+    Page(
+        path="/blog/{id}",
+        path_params=[Param(name="id", values=["1", "2", "3"])],
+    ),
+]
+
+# Initialize SiteMapr with your website's base URL and the defined pages
+sitemapr = SiteMapr(base_url="https://example.com", pages=pages)
+
+# Save the sitemap to the specified directory
+sitemapr.save("/path/to/your/sitemap/directory")
+```
+
+## License
+
+`sitemapr` is released under the MIT License. See the LICENSE file for more details.
+

sitemapr-0.1.0/README.md

@@ -0,0 +1,67 @@
+# sitemapr
+
+`sitemapr` is a Python library designed to generate and save sitemaps for websites. It allows for the creation of detailed sitemaps with customizable parameters, making it easier for search engines to crawl and index web pages efficiently.
+
+## Features
+
+- Generate sitemaps with dynamic URL parameters.
+- Split large sitemaps into chunks to comply with sitemap index specifications.
+- Customizable base URLs for sitemaps and websites.
+
+## Installation
+
+SiteMapr can be easily installed using pip. Ensure you have pip installed and run the following command:
+
+```sh
+pip install sitemapr
+```
+
+This command will download and install SiteMapr along with its dependencies.
+
+## Quick Start
+
+Here's how to quickly generate a sitemap for your website using SiteMapr:
+
+1. **Define Your Pages**: First, define the pages you want to include in your sitemap, including any dynamic path or query parameters.
+
+2. **Create a SiteMapr Instance**: Initialize SiteMapr with your website's base URL and the pages you've defined.
+
+3. **Save Your Sitemap**: Choose a directory and save your sitemap, specifying chunk sizes if needed.
+
+### Example
+
+```python
+from sitemapr import Page, Param, SiteMapr
+
+# Define the pages of your site
+pages = [
+    Page(
+        path="",
+        query_params=[
+            Param(name="page", values=["home", "about", "contact"]),
+            Param(name="sort", values=["asc", "desc"]),
+        ],
+    ),
+    Page(
+        path="/blog",
+        query_params=[
+            Param(name="page", values=["1", "2", "3"]),
+            Param(name="sort", values=["asc", "desc"]),
+        ],
+    ),
+    Page(
+        path="/blog/{id}",
+        path_params=[Param(name="id", values=["1", "2", "3"])],
+    ),
+]
+
+# Initialize SiteMapr with your website's base URL and the defined pages
+sitemapr = SiteMapr(base_url="https://example.com", pages=pages)
+
+# Save the sitemap to the specified directory
+sitemapr.save("/path/to/your/sitemap/directory")
+```
+
+## License
+
+`sitemapr` is released under the MIT License. See the LICENSE file for more details.

sitemapr-0.1.0/pyproject.toml

@@ -0,0 +1,53 @@
+[tool.poetry]
+name = "sitemapr"
+version = "0.1.0"
+description = "sitemapr is a library that generates sitemaps for SPA websites with declaritve configuration in Python."
+authors = ["sjquant <seonujang92@gmail.com>"]
+license = "MIT"
+readme = "README.md"
+
+[tool.poetry.dependencies]
+python = "^3.11"
+typer = "^0.9.0"
+pydantic = "^2.6.3"
+
+[tool.poetry.group.dev.dependencies]
+ruff = "^0.2.2"
+pyright = "^1.1.351"
+pytest = "^8.0.2"
+
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.ruff]
+line-length = 100
+fix = true
+exclude = [
+    '*.pyi',
+    "site-packages",
+    ".mypy_cache",
+    ".ruff_cache",
+]
+target-version = "py311"
+
+[tool.ruff.lint]
+select = [
+    "E",  # pycodestyle errors
+    "W",  # pycodestyle warnings
+    "F",  # pyflakes
+    "I",  # isort
+    "B",  # flake8-bugbear
+    "C4", # flake8-comprehensions
+    "UP", # pyupgrade
+]
+
+[tool.pyright]
+include = ["src"]
+exclude = ["**/node_modules",
+    "**/__pycache__",
+    "src/experimental",
+    "src/typestubs"
+]
+pythonVersion = "3.11"
+typeCheckingMode = "strict"

sitemapr-0.1.0/sitemapr/__init__.py

@@ -0,0 +1,4 @@
+from .core import SiteMapr
+from .models import Page, Param, SiteMapUrl
+
+__all__ = ["SiteMapr", "Page", "Param", "SiteMapUrl"]

sitemapr-0.1.0/sitemapr/core.py

@@ -0,0 +1,125 @@
+from collections.abc import Iterator
+from io import TextIOWrapper
+from itertools import product
+from urllib.parse import urlencode
+
+from sitemapr.models import Page, Param, SiteMapUrl
+
+
+class SiteMapr:
+    """
+    A class for generating and saving sitemaps.
+
+    Args:
+        base_url: The base URL of the website.
+        pages: A list of Page objects representing the pages to include in the sitemap.
+        sitemap_base_url: The base URL for the sitemap. Defaults to None, which uses the base_url.
+    """
+
+    def __init__(
+        self, base_url: str, pages: list[Page], *, sitemap_base_url: str | None = None
+    ):
+        self._base_url = base_url
+        self._sitemap_base_url = sitemap_base_url or base_url
+        self._pages = pages
+
+    def save(self, dirname: str, *, chunk_size: int = 50000) -> None:
+        """
+        Save the sitemap to the specified directory.
+
+        Args:
+            dirname: The directory path where the sitemap will be saved.
+            chunk_size: The number of URLs to include in each chunk. Defaults to 50000.
+        """
+        chunk: list[SiteMapUrl] = []
+        idx = 0
+        for url in self.iter_urls():
+            if len(chunk) == chunk_size:
+                self._save_chunk(dirname, idx, chunk)
+                idx += 1
+                chunk.clear()
+
+            chunk.append(url)
+
+        if not chunk:
+            return
+
+        if idx == 0:
+            with open(f"{dirname}/sitemap.xml", "w") as f:
+                self._write_urls(f, chunk)
+        else:
+            self._save_chunk(dirname, idx, chunk)
+
+        if idx > 0:
+            self._write_index_file(dirname, idx)
+
+    def _save_chunk(self, dirname: str, idx: int, chunk: list[SiteMapUrl]) -> None:
+        with open(f"{dirname}/sitemap-{idx}.xml", "w") as f:
+            self._write_urls(f, chunk)
+
+    def _write_index_file(self, dirname: str, idx: int) -> None:
+        with open(f"{dirname}/sitemap.xml", "w") as f:
+            f.write(
+                '<?xml version="1.0" encoding="UTF-8"?><sitemapindex xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">'
+            )
+            for i in range(idx + 1):
+                f.write(
+                    f"<sitemap><loc>{self._sitemap_base_url}/sitemap-{i}.xml</loc></sitemap>"
+                )
+            f.write("</sitemapindex>")
+
+    def _write_urls(self, f: TextIOWrapper, urls: list[SiteMapUrl]):
+        f.write(
+            '<?xml version="1.0" encoding="UTF-8"?><urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">'
+        )
+        for url in urls:
+            f.write(f"<url><loc>{url.loc}</loc>")
+            if url.lastmod:
+                f.write(f"<lastmod>{url.lastmod}</lastmod>")
+            if url.changefreq:
+                f.write(f"<changefreq>{url.changefreq}</changefreq>")
+            if url.priority:
+                f.write(f"<priority>{url.priority}</priority>")
+            f.write("</url>")
+        f.write("</urlset>")
+
+    def iter_urls(self) -> Iterator[SiteMapUrl]:
+        """
+        Iterates over the URLs in the sitemap.
+
+        Yields:
+            SiteMapUrl: A SiteMapUrl object representing a URL in the sitemap.
+        """
+        for page in self._pages:
+            yield from self._iter_page(page)
+
+    def _iter_page(self, page: Page) -> Iterator[SiteMapUrl]:
+        query_param_combinations = self._get_param_combinations(page.query_params)
+        path_param_combinations: list[dict[str, str]] = self._get_param_combinations(
+            page.path_params
+        )
+        for query_params, path_params in product(
+            query_param_combinations, path_param_combinations
+        ):
+            path = page.path.format(**path_params)
+            query_string = urlencode(query_params)
+            loc = (
+                f"{self._base_url}{path}?{query_string}"
+                if query_string
+                else f"{self._base_url}{path}"
+            )
+            yield SiteMapUrl(loc=loc)
+
+    def _get_param_combinations(
+        self, params: list[Param] | None
+    ) -> list[dict[str, str]]:
+        if not params:
+            return [{}]
+
+        combinations: list[dict[str, str]] = []
+        for values in product(*[param.values for param in params]):
+            combination = {
+                param.name: value for param, value in zip(params, values, strict=False)
+            }
+            combinations.append(combination)
+        return combinations

sitemapr-0.1.0/sitemapr/models.py

@@ -0,0 +1,26 @@
+from typing import Literal
+
+from pydantic import BaseModel
+
+ChangeFreq = Literal[
+    "always", "hourly", "daily", "weekly", "monthly", "yearly", "never"
+]
+
+
+class Param(BaseModel):
+    name: str
+    values: list[str] = []
+
+
+class Page(BaseModel):
+    path: str
+    query_params: list[Param] = []
+    path_params: list[Param] = []
+
+
+class SiteMapUrl(BaseModel):
+    # Refer to https://developers.google.com/search/docs/crawling-indexing/sitemaps/build-sitemap?hl=ko#xml
+    loc: str
+    lastmod: str | None = None
+    changefreq: ChangeFreq | None = None  # Google ignores this
+    priority: float | None = None  # Google ignores this