Metadata-Version: 2.1
Name: hrefs
Version: 0.8
Summary: Hyperlinks for pydantic models
Author-email: Jaakko Moisio <jaakko@moisio.fi>
Requires-Python: >=3.7
Description-Content-Type: text/x-rst
Classifier: License :: OSI Approved :: MIT License
Classifier: Environment :: Web Environment
Classifier: Framework :: FastAPI
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.7
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: Topic :: Internet
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Software Development
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Dist: pydantic>=1.8
Requires-Dist: starlette
Requires-Dist: typing_extensions
Requires-Dist: sphinx ; extra == "doc"
Requires-Dist: sphinx-rtd-theme ; extra == "doc"
Requires-Dist: tox>=3.24 ; extra == "test"
Requires-Dist: pytest>=7.2 ; extra == "test"
Requires-Dist: hypothesis>=6.68 ; extra == "test"
Requires-Dist: fastapi>=0.92 ; extra == "test"
Requires-Dist: black>=23.1 ; extra == "test"
Requires-Dist: pylint>=2.16 ; extra == "test"
Requires-Dist: mypy>=1.0 ; extra == "test"
Requires-Dist: httpx>=0.23 ; extra == "test"
Project-URL: Documentation, https://hrefs.readthedocs.io/
Project-URL: Source, https://github.com/jasujm/hrefs
Provides-Extra: doc
Provides-Extra: test

Hyperlinks for pydantic models
==============================

In a typical web application relationships between resources are modeled by
primary and foreign keys in a database (integers, UUIDs, etc.). The most natural
way to represent relationships in REST APIs is by URLs to the related resources
(explained in `this blog
<https://cloud.google.com/blog/products/application-development/api-design-why-you-should-use-links-not-keys-to-represent-relationships-in-apis>`_).

``hrefs`` makes it easy to add hyperlinks between `pydantic
<https://pydantic-docs.helpmanual.io/>`_ models in a declarative way. Just
declare a ``Href`` field and the library will automatically convert between keys
and URLs:

.. code-block:: python

   class Book(ReferrableModel):
       id: int

       class Config:
           details_view = "get_book"

   class Library(BaseModel):
       books: List[Href[Book]]

   @app.get("/library")
   def get_library():
       # Will produce something like:
       # {"books":["http://example.com/books/1","http://example.com/books/2","http://example.com/books/3"]}
       return Library(books=[1,2,3]).json()

``hrefs`` was written especially with `FastAPI <https://fastapi.tiangolo.com/>`_
in mind, but integrates into any application or framework using pydantic to
parse and serialize models.

Check out the `documentation <https://hrefs.readthedocs.io/>`_ to get started!

Installation
------------

Install the library using ``pip`` or your favorite package management tool:

.. code-block:: console

   $ pip install hrefs

