diff --git a/README.md b/README.md index 712167ffd6..93e9e4461f 100644 --- a/README.md +++ b/README.md @@ -6,30 +6,30 @@ SQLModel, SQL databases in Python, designed for simplicity, compatibility, and robustness.

- + Test - + Publish - + Coverage - + Package version

--- -**Documentation**: https://sqlmodel.tiangolo.com +**Documentation**: [https://sqlmodel.tiangolo.com](https://sqlmodel.tiangolo.com) -**Source Code**: https://github.com/fastapi/sqlmodel +**Source Code**: [https://github.com/fastapi/sqlmodel](https://github.com/fastapi/sqlmodel) --- SQLModel is a library for interacting with SQL databases from Python code, with Python objects. It is designed to be intuitive, easy to use, highly compatible, and robust. -**SQLModel** is based on Python type annotations, and powered by Pydantic and SQLAlchemy. +**SQLModel** is based on Python type annotations, and powered by [Pydantic](https://pydantic-docs.helpmanual.io/) and [SQLAlchemy](https://sqlalchemy.org/). The key features are: @@ -49,9 +49,9 @@ The key features are: ## SQL Databases in FastAPI - + -**SQLModel** is designed to simplify interacting with SQL databases in FastAPI applications, it was created by the same author. 😁 +**SQLModel** is designed to simplify interacting with SQL databases in [FastAPI](https://fastapi.tiangolo.com) applications, it was created by the same [author](https://tiangolo.com/). 😁 It combines SQLAlchemy and Pydantic and tries to simplify the code you write as much as possible, allowing you to reduce the **code duplication to a minimum**, but while getting the **best developer experience** possible. @@ -59,13 +59,13 @@ It combines SQLAlchemy and Pydantic and tries to simplify the code you write as ## Requirements -A recent and currently supported version of Python. +A recent and currently supported [version of Python](https://www.python.org/downloads/). As **SQLModel** is based on **Pydantic** and **SQLAlchemy**, it requires them. They will be automatically installed when you install SQLModel. ## Installation -Make sure you create a virtual environment, activate it, and then install SQLModel, for example with: +Make sure you create a [virtual environment](https://sqlmodel.tiangolo.com/virtual-environments/), activate it, and then install SQLModel, for example with:
@@ -79,7 +79,7 @@ Successfully installed sqlmodel ## Example -For an introduction to databases, SQL, and everything else, see the SQLModel documentation. +For an introduction to databases, SQL, and everything else, see the [SQLModel documentation](https://sqlmodel.tiangolo.com/databases/). Here's a quick example. ✨ diff --git a/docs/advanced/decimal.md b/docs/advanced/decimal.md index ce971b201b..c299decfec 100644 --- a/docs/advanced/decimal.md +++ b/docs/advanced/decimal.md @@ -11,7 +11,7 @@ As an example, if you open Python and sum `1.1` + `2.2` you would expect to see 3.3000000000000003 ``` -This is because of the way numbers are stored in "ones and zeros" (binary). But Python has a module and some types to have strict decimal values. You can read more about it in the official Python docs for Decimal. +This is because of the way numbers are stored in "ones and zeros" (binary). But Python has a module and some types to have strict decimal values. You can read more about it in the official [Python docs for Decimal](https://docs.python.org/3/library/decimal.html). Because databases store data in the same ways as computers (in binary), they would have the same types of issues. And because of that, they also have a special **decimal** type. @@ -19,13 +19,13 @@ In most cases this would probably not be a problem, for example measuring views ## Decimal Types -Pydantic has special support for `Decimal` types. +Pydantic has special support for [`Decimal` types](https://docs.pydantic.dev/latest/api/standard_library_types/#decimaldecimal). When you use `Decimal` you can specify the number of digits and decimal places to support in the `Field()` function. They will be validated by Pydantic (for example when using FastAPI) and the same information will also be used for the database columns. /// info -For the database, **SQLModel** will use SQLAlchemy's `DECIMAL` type. +For the database, **SQLModel** will use [SQLAlchemy's `DECIMAL` type](https://docs.sqlalchemy.org/en/20/core/type_basics.html#sqlalchemy.types.DECIMAL). /// diff --git a/docs/advanced/uuid.md b/docs/advanced/uuid.md index abfcfeda2b..d8b626ff81 100644 --- a/docs/advanced/uuid.md +++ b/docs/advanced/uuid.md @@ -82,9 +82,9 @@ This means that the UUID will be generated in the Python code, **before sending {* ./docs_src/advanced/uuid/tutorial001_py310.py ln[1:10] hl[1,7] *} -Pydantic has support for `UUID` types. +Pydantic has support for [`UUID` types](https://docs.pydantic.dev/latest/api/standard_library_types/#uuid). -For the database, **SQLModel** internally uses SQLAlchemy's `Uuid` type. +For the database, **SQLModel** internally uses [SQLAlchemy's `Uuid` type](https://docs.sqlalchemy.org/en/20/core/type_basics.html#sqlalchemy.types.Uuid). ### Create a Record with a UUID @@ -174,5 +174,5 @@ Selected hero ID: You can learn more about **UUIDs** in: -* The official Python docs for UUID. -* The Wikipedia for UUID. +* The official [Python docs for UUID](https://docs.python.org/3/library/uuid.html). +* The [Wikipedia for UUID](https://en.wikipedia.org/wiki/Universally_unique_identifier). diff --git a/docs/contributing.md b/docs/contributing.md index eaa2a5df46..42e81e3650 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -1,10 +1,10 @@ # Contributing -First, you might want to see the basic ways to [help SQLModel and get help](help.md){.internal-link target=_blank}. +First, you might want to see the basic ways to [help SQLModel and get help](help.md). ## Developing -If you already cloned the sqlmodel repository and you want to deep dive in the code, here are some guidelines to set up your environment. +If you already cloned the [sqlmodel repository](https://github.com/fastapi/sqlmodel) and you want to deep dive in the code, here are some guidelines to set up your environment. ### Install Requirements Using `uv` @@ -112,7 +112,7 @@ $ mkdocs serve --dev-addr 8008 The instructions here show you how to use the script at `./scripts/docs.py` with the `python` program directly. -But you can also use Typer CLI, and you will get autocompletion in your terminal for the commands after installing completion. +But you can also use [Typer CLI](https://typer.tiangolo.com/typer-cli/), and you will get autocompletion in your terminal for the commands after installing completion. If you install Typer CLI, you can install completion with: @@ -129,7 +129,7 @@ Completion will take effect once you restart the terminal. ### Docs Structure -The documentation uses MkDocs. +The documentation uses [MkDocs](https://www.mkdocs.org/). And there are extra tools/scripts in place in `./scripts/docs.py`. @@ -175,7 +175,7 @@ The same applies to comments and descriptions, please don't copy paste the conte ### Human Effort Denial of Service -Using automated tools and AI to submit PRs or comments that we have to carefully review and handle would be the equivalent of a Denial-of-service attack on our human effort. +Using automated tools and AI to submit PRs or comments that we have to carefully review and handle would be the equivalent of a [Denial-of-service attack](https://en.wikipedia.org/wiki/Denial-of-service_attack) on our human effort. It would be very little effort from the person submitting the PR (an LLM prompt) that generates a large amount of effort on our side (carefully reviewing code). diff --git a/docs/databases.md b/docs/databases.md index de25ebb4cb..a6de1a7e22 100644 --- a/docs/databases.md +++ b/docs/databases.md @@ -319,7 +319,7 @@ I'll tell you more about SQL, SQLModel, how to use them, and how they are relate /// info | Technical Details -SQLModel is built on top of SQLAlchemy. It is, in fact, just SQLAlchemy and Pydantic mixed together with some sugar on top. +SQLModel is built on top of SQLAlchemy. It is, in fact, just [SQLAlchemy](https://www.sqlalchemy.org/) and [Pydantic](https://pydantic-docs.helpmanual.io/) mixed together with some sugar on top. /// diff --git a/docs/db-to-code.md b/docs/db-to-code.md index fbba54c162..4f5fa35ccd 100644 --- a/docs/db-to-code.md +++ b/docs/db-to-code.md @@ -111,7 +111,7 @@ DROP TABLE hero; That is how you tell the database in SQL to delete the entire table `hero`. -Nooooo! We lost all the data in the `hero` table! πŸ’₯😱 +[Nooooo!](https://theuselessweb.site/nooooooooooooooo/) We lost all the data in the `hero` table! πŸ’₯😱 ### SQL Sanitization @@ -119,7 +119,7 @@ The process of making sure that whatever the external user sends is safe to use It comes by default in **SQLModel** (thanks to SQLAlchemy). And many other similar tools would also provide that functionality among many other features. -Now you are ready for a joke from xkcd: +Now you are ready for [a joke from xkcd](https://xkcd.com/327/): ![Exploits of a Mom](https://imgs.xkcd.com/comics/exploits_of_a_mom.png) @@ -292,7 +292,7 @@ It's actually a simple idea with a very academic and mathematical name. πŸ˜… So, an **ORM** is a library that translates from SQL to code, and from code to SQL. All using classes and objects. -There are many ORMs available apart from **SQLModel**, you can read more about some of them in [Alternatives, Inspiration and Comparisons](alternatives.md){.internal-link target=_blank} +There are many ORMs available apart from **SQLModel**, you can read more about some of them in [Alternatives, Inspiration and Comparisons](alternatives.md) ## SQL Table Names diff --git a/docs/environment-variables.md b/docs/environment-variables.md index bd8b2a06d0..4d5a6983e7 100644 --- a/docs/environment-variables.md +++ b/docs/environment-variables.md @@ -67,7 +67,7 @@ print(f"Hello {name} from Python") /// tip -The second argument to `os.getenv()` is the default value to return. +The second argument to [`os.getenv()`](https://docs.python.org/3.8/library/os.html#os.getenv) is the default value to return. If not provided, it's `None` by default, here we provide `"World"` as the default value to use. @@ -155,7 +155,7 @@ Hello World from Python /// tip -You can read more about it at The Twelve-Factor App: Config. +You can read more about it at [The Twelve-Factor App: Config](https://12factor.net/config). /// @@ -287,13 +287,13 @@ $ C:\opt\custompython\bin\python //// -This information will be useful when learning about [Virtual Environments](virtual-environments.md){.internal-link target=_blank}. +This information will be useful when learning about [Virtual Environments](virtual-environments.md). ## Conclusion With this you should have a basic understanding of what **environment variables** are and how to use them in Python. -You can also read more about them in the Wikipedia for Environment Variable. +You can also read more about them in the [Wikipedia for Environment Variable](https://en.wikipedia.org/wiki/Environment_variable). In many cases it's not very obvious how environment variables would be useful and applicable right away. But they keep showing up in many different scenarios when you are developing, so it's good to know about them. diff --git a/docs/features.md b/docs/features.md index 2f2e873105..204c23697e 100644 --- a/docs/features.md +++ b/docs/features.md @@ -2,9 +2,9 @@ ## Designed for **FastAPI** -**SQLModel** was created by the same author of FastAPI. +**SQLModel** was created by the same [author](https://tiangolo.com/) of FastAPI. - + It follows the same design and ideas, and it was created to be the most intuitive way to interact with SQL databases in FastAPI applications. @@ -14,9 +14,9 @@ Nevertheless, SQLModel is completely **independent** of FastAPI and can be used It's all based on standard modern **Python** type annotations. No new syntax to learn. Just standard modern Python. -If you need a 2 minute refresher of how to use Python types (even if you don't use SQLModel or FastAPI), check the FastAPI tutorial section: Python types intro. +If you need a 2 minute refresher of how to use Python types (even if you don't use SQLModel or FastAPI), check the FastAPI tutorial section: [Python types intro](https://fastapi.tiangolo.com/python-types/). -You will also see a 20 seconds refresher on the section [Tutorial - User Guide: First Steps](tutorial/index.md){.internal-link target=_blank}. +You will also see a 20 seconds refresher on the section [Tutorial - User Guide: First Steps](tutorial/index.md). ## Editor support @@ -24,11 +24,11 @@ You will also see a 20 seconds refresher on the section [Tutorial - User Guide: Here's how your editor might help you: -* in Visual Studio Code: +* in [Visual Studio Code](https://code.visualstudio.com/): -* in PyCharm: +* in [PyCharm](https://www.jetbrains.com/pycharm/): @@ -36,7 +36,7 @@ You will get completion for everything while writing the **minimum** amount of c You won't need to keep guessing the types of different attributes in your models, if they could be `None`, etc. Your editor will be able to help you with everything because **SQLModel** is based on **standard Python type annotations**. -**SQLModel** adopts PEP 681 for Python type annotations to ensure the **best developer experience**, so you will get inline errors and autocompletion even while creating new model instances. +**SQLModel** adopts [PEP 681](https://peps.python.org/pep-0681/) for Python type annotations to ensure the **best developer experience**, so you will get inline errors and autocompletion even while creating new model instances. @@ -76,7 +76,7 @@ Underneath, ✨ a **SQLModel** model is also a **SQLAlchemy** model. ✨ There was **a lot** of research and effort dedicated to make it that way. In particular, there was a lot of effort and experimentation in making a single model be **both a SQLAlchemy model and a Pydantic** model at the same time. -That means that you get all the power, robustness, and certainty of SQLAlchemy, the most widely used database library in Python. +That means that you get all the power, robustness, and certainty of SQLAlchemy, the [most widely used database library in Python](https://lp.jetbrains.com/python-developers-survey-2024/#orms). **SQLModel** provides its own utilities to improve the developer experience, but underneath, it uses all of SQLAlchemy. diff --git a/docs/help.md b/docs/help.md index 6e5fe581f7..7e52e87009 100644 --- a/docs/help.md +++ b/docs/help.md @@ -12,7 +12,7 @@ And there are several ways to get help too. ## Subscribe to the FastAPI and Friends newsletter -You can subscribe to the (infrequent) **FastAPI and friends** newsletter to stay updated about: +You can subscribe to the (infrequent) [**FastAPI and friends** newsletter](https://fastapi.tiangolo.com/newsletter) to stay updated about: * News about FastAPI and friends, including SQLModel πŸš€ * Guides πŸ“ @@ -22,13 +22,13 @@ You can subscribe to the (infrequent) https://github.com/fastapi/sqlmodel. ⭐️ +You can "star" SQLModel in GitHub (clicking the star button at the top right): [https://github.com/fastapi/sqlmodel](https://github.com/fastapi/sqlmodel). ⭐️ By adding a star, other users will be able to find it more easily and see that it has been already useful for others. ## Watch the GitHub repository for releases -You can "watch" SQLModel in GitHub (clicking the "watch" button at the top right): https://github.com/fastapi/sqlmodel. πŸ‘€ +You can "watch" SQLModel in GitHub (clicking the "watch" button at the top right): [https://github.com/fastapi/sqlmodel](https://github.com/fastapi/sqlmodel). πŸ‘€ There you can select "Releases only". @@ -36,25 +36,25 @@ By doing it, you will receive notifications (in your email) whenever there's a n ## Connect with the author -You can connect with me (SebastiΓ‘n RamΓ­rez / `tiangolo`), the author. +You can connect with [me (SebastiΓ‘n RamΓ­rez / `tiangolo`)](https://tiangolo.com), the author. You can: -* Follow me on **GitHub**. +* [Follow me on **GitHub**](https://github.com/tiangolo). * See other Open Source projects I have created that could help you. * Follow me to see when I create a new Open Source project. -* Follow me on **Twitter**. +* [Follow me on **Twitter**](https://twitter.com/tiangolo). * Tell me how you use SQLModel (I love to hear that). * Hear when I make announcements or release new tools. -* Connect with me on **Linkedin**. +* [Connect with me on **Linkedin**](https://www.linkedin.com/in/tiangolo/). * Hear when I make announcements or release new tools (although I use Twitter more often πŸ€·β€β™‚). -* Read what I write (or follow me) on **Dev.to** or **Medium**. +* Read what I write (or follow me) on [**Dev.to**](https://dev.to/tiangolo) or [**Medium**](https://medium.com/@tiangolo). * Read other ideas, articles, and read about tools I have created. * Follow me to read when I publish something new. ## Tweet about **SQLModel** -Tweet about **SQLModel** and let me and others know why you like it. πŸŽ‰ +[Tweet about **SQLModel**](https://twitter.com/compose/tweet?text=I'm loving SQLModel because... https://github.com/fastapi/sqlmodel cc: @tiangolo) and let me and others know why you like it. πŸŽ‰ I love to hear about how **SQLModel** is being used, what you have liked in it, in which project/company are you using it, etc. @@ -62,8 +62,8 @@ I love to hear about how **SQLModel** is being used, what you have liked in it, You can try and help others with their questions in: -* GitHub Discussions -* GitHub Issues +* [GitHub Discussions](https://github.com/fastapi/sqlmodel/discussions/categories/questions?discussions_q=category%3AQuestions+is%3Aunanswered) +* [GitHub Issues](https://github.com/fastapi/sqlmodel/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc+label%3Aquestion+-label%3Aanswered+) In many cases you might already know the answer for those questions. πŸ€“ @@ -91,7 +91,7 @@ For most of the cases and most of the questions there's something related to the In many cases they will only copy a fragment of the code, but that's not enough to **reproduce the problem**. -* You can ask them to provide a minimal, reproducible, example, that you can **copy-paste** and run locally to see the same error or behavior they are seeing, or to understand their use case better. +* You can ask them to provide a [minimal, reproducible, example](https://stackoverflow.com/help/minimal-reproducible-example), that you can **copy-paste** and run locally to see the same error or behavior they are seeing, or to understand their use case better. * If you are feeling too generous, you can try to **create an example** like that yourself, just based on the description of the problem. Just have in mind that this might take a lot of time and it might be better to ask them to clarify the problem first. @@ -112,7 +112,7 @@ If they reply, there's a high chance you would have solved their problem, congra ## Watch the GitHub repository -You can "watch" SQLModel in GitHub (clicking the "watch" button at the top right): https://github.com/fastapi/sqlmodel. πŸ‘€ +You can "watch" SQLModel in GitHub (clicking the "watch" button at the top right): [https://github.com/fastapi/sqlmodel](https://github.com/fastapi/sqlmodel). πŸ‘€ If you select "Watching" instead of "Releases only" you will receive notifications when someone creates a new issue or question. You can also specify that you only want to be notified about new issues, or discussions, or PRs, etc. @@ -120,7 +120,7 @@ Then you can try and help them solve those questions. ## Ask Questions -You can create a new question in the GitHub repository, for example to: +You can [create a new question](https://github.com/fastapi/sqlmodel/discussions/new?category=questions) in the GitHub repository, for example to: * Ask a **question** or ask about a **problem**. * Suggest a new **feature**. @@ -183,7 +183,7 @@ So, it's really important that you actually read and run the code, and let me kn ## Create a Pull Request -You can [contribute](contributing.md){.internal-link target=_blank} to the source code with Pull Requests, for example: +You can [contribute](contributing.md) to the source code with Pull Requests, for example: * To fix a typo you found on the documentation. * To propose new documentation sections. @@ -201,8 +201,8 @@ There's a lot of work to do, and for most of it, **YOU** can do it. The main tasks that you can do right now are: -* [Help others with questions in GitHub](#help-others-with-questions-in-github){.internal-link target=_blank} (see the section above). -* [Review Pull Requests](#review-pull-requests){.internal-link target=_blank} (see the section above). +* [Help others with questions in GitHub](#help-others-with-questions-in-github) (see the section above). +* [Review Pull Requests](#review-pull-requests) (see the section above). Those two tasks are what **consume time the most**. That's the main work of maintaining SQLModel. @@ -210,11 +210,11 @@ If you can help me with that, **you are helping me maintain SQLModel** and makin ## Join the chat -Join the πŸ‘₯ FastAPI and Friends Discord chat server πŸ‘₯ and hang out with others in the community. There's a `#sqlmodel` channel. +Join the πŸ‘₯ [FastAPI and Friends Discord chat server](https://discord.gg/VQjSZaeJmf) πŸ‘₯ and hang out with others in the community. There's a `#sqlmodel` channel. /// tip -For questions, ask them in GitHub Discussions, there's a much better chance you will receive help there. +For questions, ask them in [GitHub Discussions](https://github.com/fastapi/sqlmodel/discussions/new?category=questions), there's a much better chance you will receive help there. Use the chat only for other general conversations. @@ -232,7 +232,7 @@ On the other side, there are thousands of users in the chat, so there's a high c ## Sponsor the author -You can also financially support the author (me) through GitHub sponsors. +You can also financially support the author (me) through [GitHub sponsors](https://github.com/sponsors/tiangolo). There you could buy me a coffee β˜•οΈ to say thanks. πŸ˜„ @@ -242,8 +242,8 @@ As you have seen in the documentation, SQLModel stands on the shoulders of giant You can also sponsor: -* Samuel Colvin (Pydantic) -* SQLAlchemy +* [Samuel Colvin (Pydantic)](https://github.com/sponsors/samuelcolvin) +* [SQLAlchemy](https://github.com/sponsors/sqlalchemy) --- diff --git a/docs/index.md b/docs/index.md index cd48b91385..2bc3d1998c 100644 --- a/docs/index.md +++ b/docs/index.md @@ -12,30 +12,30 @@ SQLModel, SQL databases in Python, designed for simplicity, compatibility, and robustness.

- + Test - + Publish - + Coverage - + Package version

--- -**Documentation**: https://sqlmodel.tiangolo.com +**Documentation**: [https://sqlmodel.tiangolo.com](https://sqlmodel.tiangolo.com) -**Source Code**: https://github.com/fastapi/sqlmodel +**Source Code**: [https://github.com/fastapi/sqlmodel](https://github.com/fastapi/sqlmodel) --- SQLModel is a library for interacting with SQL databases from Python code, with Python objects. It is designed to be intuitive, easy to use, highly compatible, and robust. -**SQLModel** is based on Python type annotations, and powered by Pydantic and SQLAlchemy. +**SQLModel** is based on Python type annotations, and powered by [Pydantic](https://pydantic-docs.helpmanual.io/) and [SQLAlchemy](https://sqlalchemy.org/). The key features are: @@ -51,10 +51,10 @@ The key features are: {% if sponsors %} {% for sponsor in sponsors.gold -%} - + {% endfor -%} {%- for sponsor in sponsors.silver -%} - + {% endfor %} {% endif %} @@ -62,9 +62,9 @@ The key features are: ## SQL Databases in FastAPI - + -**SQLModel** is designed to simplify interacting with SQL databases in FastAPI applications, it was created by the same author. 😁 +**SQLModel** is designed to simplify interacting with SQL databases in [FastAPI](https://fastapi.tiangolo.com) applications, it was created by the same [author](https://tiangolo.com/). 😁 It combines SQLAlchemy and Pydantic and tries to simplify the code you write as much as possible, allowing you to reduce the **code duplication to a minimum**, but while getting the **best developer experience** possible. @@ -72,13 +72,13 @@ It combines SQLAlchemy and Pydantic and tries to simplify the code you write as ## Requirements -A recent and currently supported version of Python. +A recent and currently supported [version of Python](https://www.python.org/downloads/). As **SQLModel** is based on **Pydantic** and **SQLAlchemy**, it requires them. They will be automatically installed when you install SQLModel. ## Installation -Make sure you create a virtual environment, activate it, and then install SQLModel, for example with: +Make sure you create a [virtual environment](https://sqlmodel.tiangolo.com/virtual-environments/), activate it, and then install SQLModel, for example with:
@@ -92,7 +92,7 @@ Successfully installed sqlmodel ## Example -For an introduction to databases, SQL, and everything else, see the SQLModel documentation. +For an introduction to databases, SQL, and everything else, see the [SQLModel documentation](https://sqlmodel.tiangolo.com/databases/). Here's a quick example. ✨ diff --git a/docs/install.md b/docs/install.md index 129df3512b..048c3c6437 100644 --- a/docs/install.md +++ b/docs/install.md @@ -1,6 +1,6 @@ # Install **SQLModel** -Create a project directory, create a [virtual environment](virtual-environments.md){.internal-link target=_blank}, activate it, and then install **SQLModel**, for example with: +Create a project directory, create a [virtual environment](virtual-environments.md), activate it, and then install **SQLModel**, for example with:
@@ -12,27 +12,27 @@ Successfully installed sqlmodel pydantic sqlalchemy
-As **SQLModel** is built on top of SQLAlchemy and Pydantic, when you install `sqlmodel` they will also be automatically installed. +As **SQLModel** is built on top of [SQLAlchemy](https://www.sqlalchemy.org/) and [Pydantic](https://pydantic-docs.helpmanual.io/), when you install `sqlmodel` they will also be automatically installed. ## Install DB Browser for SQLite -Remember that [SQLite is a simple database in a single file](databases.md#a-single-file-database){.internal-link target=_blank}? +Remember that [SQLite is a simple database in a single file](databases.md#a-single-file-database)? For most of the tutorial I'll use SQLite for the examples. -Python has integrated support for SQLite, it is a single file read and processed from Python. And it doesn't need an [External Database Server](databases.md#a-server-database){.internal-link target=_blank}, so it will be perfect for learning. +Python has integrated support for SQLite, it is a single file read and processed from Python. And it doesn't need an [External Database Server](databases.md#a-server-database), so it will be perfect for learning. -In fact, SQLite is perfectly capable of handling quite big applications. At some point you might want to migrate to a server-based database like PostgreSQL (which is also free). But for now we'll stick to SQLite. +In fact, SQLite is perfectly capable of handling quite big applications. At some point you might want to migrate to a server-based database like [PostgreSQL](https://www.postgresql.org/) (which is also free). But for now we'll stick to SQLite. Through the tutorial I will show you SQL fragments, and Python examples. And I hope (and expect 🧐) you to actually run them, and verify that the database is working as expected and showing you the same data. -To be able to explore the SQLite file yourself, independent of Python code (and probably at the same time), I recommend you use DB Browser for SQLite. +To be able to explore the SQLite file yourself, independent of Python code (and probably at the same time), I recommend you use [DB Browser for SQLite](https://sqlitebrowser.org/). It's a great and simple program to interact with SQLite databases (SQLite files) in a nice user interface. -Go ahead and Install DB Browser for SQLite, it's free. +Go ahead and [Install DB Browser for SQLite](https://sqlitebrowser.org/), it's free. ## Next Steps diff --git a/docs/management-tasks.md b/docs/management-tasks.md index a1eb0b1863..bb2e84a101 100644 --- a/docs/management-tasks.md +++ b/docs/management-tasks.md @@ -1,6 +1,6 @@ # Repository Management Tasks -These are the tasks that can be performed to manage the SQLModel repository by [team members](./management.md#team){.internal-link target=_blank}. +These are the tasks that can be performed to manage the SQLModel repository by [team members](./management.md#team). /// tip @@ -8,9 +8,9 @@ This section is useful only to a handful of people, team members with permission /// -...so, you are a [team member of SQLModel](./management.md#team){.internal-link target=_blank}? Wow, you are so cool! 😎 +...so, you are a [team member of SQLModel](./management.md#team)? Wow, you are so cool! 😎 -You can help with everything on [Help SQLModel - Get Help](./help.md){.internal-link target=_blank} the same ways as external contributors. But additionally, there are some tasks that only you (as part of the team) can perform. +You can help with everything on [Help SQLModel - Get Help](./help.md) the same ways as external contributors. But additionally, there are some tasks that only you (as part of the team) can perform. Here are the general instructions for the tasks you can perform. @@ -40,22 +40,22 @@ For conversations that are more difficult, for example to reject a PR, you can a ## Edit PR Titles -* Edit the PR title to start with an emoji from gitmoji. +* Edit the PR title to start with an emoji from [gitmoji](https://gitmoji.dev/). * Use the emoji character, not the GitHub code. So, use `πŸ›` instead of `:bug:`. This is so that it shows up correctly outside of GitHub, for example in the release notes. * Start the title with a verb. For example `Add`, `Refactor`, `Fix`, etc. This way the title will say the action that the PR does. Like `Add support for teleporting`, instead of `Teleporting wasn't working, so this PR fixes it`. * Edit the text of the PR title to start in "imperative", like giving an order. So, instead of `Adding support for teleporting` use `Add support for teleporting`. * Try to make the title descriptive about what it achieves. If it's a feature, try to describe it, for example `Add support for teleporting` instead of `Create TeleportAdapter class`. * Do not finish the title with a period (`.`). -Once the PR is merged, a GitHub Action (latest-changes) will use the PR title to update the latest changes automatically. +Once the PR is merged, a GitHub Action ([latest-changes](https://github.com/tiangolo/latest-changes)) will use the PR title to update the latest changes automatically. So, having a nice PR title will not only look nice in GitHub, but also in the release notes. πŸ“ ## Add Labels to PRs -The same GitHub Action latest-changes uses one label in the PR to decide the section in the release notes to put this PR in. +The same GitHub Action [latest-changes](https://github.com/tiangolo/latest-changes) uses one label in the PR to decide the section in the release notes to put this PR in. -Make sure you use a supported label from the latest-changes list of labels: +Make sure you use a supported label from the [latest-changes list of labels](https://github.com/tiangolo/latest-changes#using-labels): * `breaking`: Breaking Changes * Existing code will break if they update the version without changing their code. This rarely happens, so this label is not frequently used. @@ -114,4 +114,4 @@ Dependabot will create PRs to update dependencies for several things, and those When a question in GitHub Discussions has been answered, mark the answer by clicking "Mark as answer". -You can filter discussions by `Questions` that are `Unanswered`. +You can filter discussions by [`Questions` that are `Unanswered`](https://github.com/fastapi/sqlmodel/discussions/categories/questions?discussions_q=category:Questions+is:open+is:unanswered). diff --git a/docs/management.md b/docs/management.md index 0078e364c3..768768d062 100644 --- a/docs/management.md +++ b/docs/management.md @@ -4,15 +4,15 @@ Here's a short description of how the SQLModel repository is managed and maintai ## Owner -I, @tiangolo, am the creator and owner of the SQLModel repository. πŸ€“ +I, [@tiangolo](https://github.com/tiangolo), am the creator and owner of the SQLModel repository. πŸ€“ -I normally give the final review to each PR before merging them. I make the final decisions on the project, I'm the BDFL. πŸ˜… +I normally give the final review to each PR before merging them. I make the final decisions on the project, I'm the [BDFL](https://en.wikipedia.org/wiki/Benevolent_dictator_for_life). πŸ˜… ## Team There's a team of people that help manage and maintain the project. 😎 -They have different levels of permissions and [specific instructions](./management-tasks.md){.internal-link target=_blank}. +They have different levels of permissions and [specific instructions](./management-tasks.md). Some of the tasks they can perform include: @@ -31,7 +31,7 @@ This is the current list of team members. 😎
{% for user in members["members"] %} -
@{{ user.login }}
+
@{{ user.login }}
{% endfor %}
@@ -42,4 +42,4 @@ Additional to them, there's a large community of people helping each other and g External contributions are very welcome and appreciated, including answering questions, submitting PRs, etc. πŸ™‡β€β™‚οΈ -There are many ways to [help maintain SQLModel](./help.md){.internal-link target=_blank}. +There are many ways to [help maintain SQLModel](./help.md). diff --git a/docs/tutorial/code-structure.md b/docs/tutorial/code-structure.md index 2c0cba526e..4b879ed7e6 100644 --- a/docs/tutorial/code-structure.md +++ b/docs/tutorial/code-structure.md @@ -91,7 +91,7 @@ Here we import the models, the engine, and the function to create all the tables ### Order Matters -Remember that [Order Matters](create-db-and-table.md#sqlmodel-metadata-order-matters){.internal-link target=_blank} when calling `SQLModel.metadata.create_all()`? +Remember that [Order Matters](create-db-and-table.md#sqlmodel-metadata-order-matters) when calling `SQLModel.metadata.create_all()`? The point of that section in the docs is that you have to import the module that has the models **before** calling `SQLModel.metadata.create_all()`. diff --git a/docs/tutorial/connect/read-connected-data.md b/docs/tutorial/connect/read-connected-data.md index 2868c69dd5..25e2e0b7b8 100644 --- a/docs/tutorial/connect/read-connected-data.md +++ b/docs/tutorial/connect/read-connected-data.md @@ -413,7 +413,7 @@ And then why we didn't include `Hero` in the `.join()`. πŸ€” In SQLModel (actually in SQLAlchemy), all these functions and tools try to **replicate** how it would be to work with the **SQL** language. -Remember that [`SELECT` defines the columns to get and `WHERE` how to filter them?](../where.md#select-and-where){.internal-link target=_blank}. +Remember that [`SELECT` defines the columns to get and `WHERE` how to filter them?](../where.md#select-and-where). This also applies here, but with `JOIN` and `ON`. diff --git a/docs/tutorial/create-db-and-table-with-db-browser.md b/docs/tutorial/create-db-and-table-with-db-browser.md index 4c535df11c..8b3bf93a12 100644 --- a/docs/tutorial/create-db-and-table-with-db-browser.md +++ b/docs/tutorial/create-db-and-table-with-db-browser.md @@ -40,7 +40,7 @@ Click the button New Database. -A dialog should show up. Go to the [project directory you created](../virtual-environments.md#create-a-project){.internal-link target=_blank} and save the file with a name of `database.db`. +A dialog should show up. Go to the [project directory you created](../virtual-environments.md#create-a-project) and save the file with a name of `database.db`. /// tip @@ -159,9 +159,9 @@ And if you go back to the Database Structure tab, you will see that y I will keep showing you small bits of SQL through this tutorial. And you don't have to be a SQL expert to use **SQLModel**. -But if you are curious and want to get a quick overview of SQL, I recommend the visual documentation from SQLite, on SQL As Understood By SQLite. +But if you are curious and want to get a quick overview of SQL, I recommend the visual documentation from SQLite, on [SQL As Understood By SQLite](https://www.sqlite.org/lang.html). -You can start with `CREATE TABLE`. +You can start with [`CREATE TABLE`](https://www.sqlite.org/lang_createtable.html). Of course, you can also go and take a full SQL course or read a book about SQL, but you don't need more than what I'll explain here on the tutorial to start being productive with **SQLModel**. πŸ€“ diff --git a/docs/tutorial/create-db-and-table.md b/docs/tutorial/create-db-and-table.md index bbd5532bae..2163956767 100644 --- a/docs/tutorial/create-db-and-table.md +++ b/docs/tutorial/create-db-and-table.md @@ -2,7 +2,7 @@ Now let's get to the code. πŸ‘©β€πŸ’» -Make sure you are inside of your project directory and with your virtual environment activated as explained in [Virtual Environments](../virtual-environments.md#create-a-project){.internal-link target=_blank}. +Make sure you are inside of your project directory and with your virtual environment activated as explained in [Virtual Environments](../virtual-environments.md#create-a-project). We will: @@ -176,7 +176,7 @@ SQLite supports a special database that lives all *in memory*. Hence, it's very {* ./docs_src/tutorial/create_db_and_table/tutorial001_py310.py ln[1:16] hl[11:12,14] *} -You can read a lot more about all the databases supported by **SQLAlchemy** (and that way supported by **SQLModel**) in the SQLAlchemy documentation. +You can read a lot more about all the databases supported by **SQLAlchemy** (and that way supported by **SQLModel**) in the [SQLAlchemy documentation](https://docs.sqlalchemy.org/en/14/core/engines.html). ### Engine Echo @@ -202,7 +202,7 @@ If you didn't know about SQLAlchemy before and are just learning **SQLModel**, y /// -You can read a lot more about the engine in the SQLAlchemy documentation. +You can read a lot more about the engine in the [SQLAlchemy documentation](https://docs.sqlalchemy.org/en/14/tutorial/engine.html). **SQLModel** defines its own `create_engine()` function. It is the same as SQLAlchemy's `create_engine()`, but with the difference that it defaults to use `future=True` (which means that it uses the style of the latest SQLAlchemy, 1.4, and the future 2.0). @@ -327,7 +327,7 @@ Put the code in a file `app.py` if you haven't already. /// tip -Remember to [activate the virtual environment](../virtual-environments.md#create-a-virtual-environment){.internal-link target=_blank} before running it. +Remember to [activate the virtual environment](../virtual-environments.md#create-a-virtual-environment) before running it. /// @@ -390,7 +390,7 @@ In the example in the previous chapter we created the table using `TEXT` for som But in this output SQLAlchemy is using `VARCHAR` instead. Let's see what's going on. -Remember that [each SQL Database has some different variations in what they support?](../databases.md#sql-the-language){.internal-link target=_blank} +Remember that [each SQL Database has some different variations in what they support?](../databases.md#sql-the-language) This is one of the differences. Each database supports some particular **data types**, like `INTEGER` and `TEXT`. @@ -484,7 +484,7 @@ from app import Hero That `if` block using `if __name__ == "__main__":` is sometimes called the "**main block**". -The official name (in the Python docs) is "**Top-level script environment**". +The official name (in the [Python docs](https://docs.python.org/3/library/__main__.html)) is "**Top-level script environment**". /// @@ -540,7 +540,7 @@ if __name__ == "__main__": /// info -For more information, check the official Python docs. +For more information, check [the official Python docs](https://docs.python.org/3/library/__main__.html). /// diff --git a/docs/tutorial/fastapi/index.md b/docs/tutorial/fastapi/index.md index 0d57ab9bd8..f837bb22b5 100644 --- a/docs/tutorial/fastapi/index.md +++ b/docs/tutorial/fastapi/index.md @@ -2,7 +2,7 @@ One of the use cases where **SQLModel** shines the most, and the main one why it was built, was to be combined with **FastAPI**. ✨ -FastAPI is a Python web framework for building web APIs created by the same author of SQLModel. FastAPI is also built on top of **Pydantic**. +[FastAPI](https://fastapi.tiangolo.com/) is a Python web framework for building web APIs created by the same [author](https://twitter.com/tiangolo) of SQLModel. FastAPI is also built on top of **Pydantic**. In this group of chapters we will see how to combine SQLModel **table models** representing tables in the SQL database as all the ones we have seen up to now, with **data models** that only represent data (which are actually just Pydantic models behind the scenes). @@ -14,4 +14,4 @@ By the end we will have a **simple** but **complete** web **API** to interact wi If you have never used FastAPI, maybe a good idea would be to go and study it a bit before continuing. -Just reading and trying the examples on the FastAPI main page should be enough, and it shouldn't take you more than **10 minutes**. +Just reading and trying the examples on the [FastAPI main page](https://fastapi.tiangolo.com/) should be enough, and it shouldn't take you more than **10 minutes**. diff --git a/docs/tutorial/fastapi/limit-and-offset.md b/docs/tutorial/fastapi/limit-and-offset.md index 1a464a664f..72ec237c20 100644 --- a/docs/tutorial/fastapi/limit-and-offset.md +++ b/docs/tutorial/fastapi/limit-and-offset.md @@ -36,9 +36,9 @@ This way, a client can decide to take fewer heroes if they want, but not more. If you need to refresh how query parameters and their validation work, check out the docs in FastAPI: -* Query Parameters -* Query Parameters and String Validations -* Path Parameters and Numeric Validations +* [Query Parameters](https://fastapi.tiangolo.com/tutorial/query-params/) +* [Query Parameters and String Validations](https://fastapi.tiangolo.com/tutorial/query-params-str-validations/) +* [Path Parameters and Numeric Validations](https://fastapi.tiangolo.com/tutorial/path-params-numeric-validations/) /// diff --git a/docs/tutorial/fastapi/multiple-models.md b/docs/tutorial/fastapi/multiple-models.md index 1bc045612b..9de7dbb14a 100644 --- a/docs/tutorial/fastapi/multiple-models.md +++ b/docs/tutorial/fastapi/multiple-models.md @@ -167,7 +167,7 @@ This will validate that all the data that we promised is there and will remove a This filtering could be very important and could be a very good security feature, for example, to make sure you filter private data, hashed passwords, etc. -You can read more about it in the FastAPI docs about Response Model. +You can read more about it in the [FastAPI docs about Response Model](https://fastapi.tiangolo.com/tutorial/response-model/). /// diff --git a/docs/tutorial/fastapi/read-one.md b/docs/tutorial/fastapi/read-one.md index 03a65a0a2d..a56a90395e 100644 --- a/docs/tutorial/fastapi/read-one.md +++ b/docs/tutorial/fastapi/read-one.md @@ -10,7 +10,7 @@ We want to get the hero based on the `id`, so we will use a **path parameter** ` /// info -If you need to refresh how *path parameters* work, including their data validation, check the FastAPI docs about Path Parameters. +If you need to refresh how *path parameters* work, including their data validation, check the [FastAPI docs about Path Parameters](https://fastapi.tiangolo.com/tutorial/path-params/). /// diff --git a/docs/tutorial/fastapi/relationships.md b/docs/tutorial/fastapi/relationships.md index f789fd930a..13ca18d650 100644 --- a/docs/tutorial/fastapi/relationships.md +++ b/docs/tutorial/fastapi/relationships.md @@ -46,7 +46,7 @@ And the same way, we declared the `TeamPublic` with only the same base fields of {* ./docs_src/tutorial/fastapi/teams/tutorial001_py310.py ln[5:7,20:21,29:34,43:44] hl[5:7,20:21,29:34,43:44] *} -Now, remember that FastAPI uses the `response_model` to validate and **filter** the response data? +Now, remember that [FastAPI uses the `response_model` to validate and **filter** the response data](https://fastapi.tiangolo.com/tutorial/response-model/)? In this case, we used `response_model=TeamPublic` and `response_model=HeroPublic`, so FastAPI will use them to filter the response data, even if we return a **table model** that includes **relationship attributes**: diff --git a/docs/tutorial/fastapi/response-model.md b/docs/tutorial/fastapi/response-model.md index f9214332c6..d93354c039 100644 --- a/docs/tutorial/fastapi/response-model.md +++ b/docs/tutorial/fastapi/response-model.md @@ -8,7 +8,7 @@ Up to now, with the code we have used, the API docs know the data the clients ha Interactive API docs UI -This interactive docs UI is powered by Swagger UI, and what Swagger UI does is to read a big JSON content that defines the API with all the data schemas (data shapes) using the standard OpenAPI, and showing it in that nice UI. +This interactive docs UI is powered by [Swagger UI](https://github.com/swagger-api/swagger-ui), and what Swagger UI does is to read a big JSON content that defines the API with all the data schemas (data shapes) using the standard [OpenAPI](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md), and showing it in that nice UI. FastAPI automatically **generates that OpenAPI** for Swagger UI to read it. @@ -48,7 +48,7 @@ FastAPI will do data validation and filtering of the response with this `respons So this works like a contract between our application and the client. -You can read more about it in the FastAPI docs about `response_model`. +You can read more about it in the [FastAPI docs about `response_model`](https://fastapi.tiangolo.com/tutorial/response-model/). ## New API Docs UI @@ -62,7 +62,7 @@ The clients will know what data they should expect. The most visible advantage of using the `response_model` is that it shows up in the API docs UI. -But there are other advantages, like that FastAPI will do automatic data validation and filtering of the response data using this model. +But there are other advantages, like that FastAPI will do automatic [data validation and filtering](https://fastapi.tiangolo.com/tutorial/response-model/) of the response data using this model. Additionally, because the schemas are defined in using a standard, there are many tools that can take advantage of this. @@ -72,7 +72,7 @@ For example, client generators, that can automatically create the code necessary If you are curious about the standards, FastAPI generates OpenAPI, that internally uses JSON Schema. -You can read about all that in the FastAPI docs - First Steps. +You can read about all that in the [FastAPI docs - First Steps](https://fastapi.tiangolo.com/tutorial/first-steps/#openapi). /// diff --git a/docs/tutorial/fastapi/session-with-dependency.md b/docs/tutorial/fastapi/session-with-dependency.md index e81e9e6745..a4e6dbf8b7 100644 --- a/docs/tutorial/fastapi/session-with-dependency.md +++ b/docs/tutorial/fastapi/session-with-dependency.md @@ -8,7 +8,7 @@ Up to now, we have been creating a session in each *path operation*, in a `with` {* ./docs_src/tutorial/fastapi/delete/tutorial001_py310.py ln[48:55] hl[50] *} -That's perfectly fine, but in many use cases we would want to use FastAPI Dependencies, for example to **verify** that the client is **logged in** and get the **current user** before executing any other code in the *path operation*. +That's perfectly fine, but in many use cases we would want to use [FastAPI Dependencies](https://fastapi.tiangolo.com/tutorial/dependencies/), for example to **verify** that the client is **logged in** and get the **current user** before executing any other code in the *path operation*. These dependencies are also very useful during **testing**, because we can **easily replace them**, and then, for example, use a new database for our tests, or put some data before the tests, etc. @@ -38,7 +38,7 @@ Here we are passing the parameter `session` that has a "default value" of `Depen Python would normally complain about that, but we can use the initial "parameter" `*,` to mark all the rest of the parameters as "keyword only", which solves the problem. -You can read more about it in the FastAPI documentation Path Parameters and Numeric Validations - Order the parameters as you need, tricks +You can read more about it in the FastAPI documentation [Path Parameters and Numeric Validations - Order the parameters as you need, tricks](https://fastapi.tiangolo.com/tutorial/path-params-numeric-validations/#order-the-parameters-as-you-need-tricks) /// @@ -86,4 +86,4 @@ You just learned how to use **FastAPI dependencies** to handle the database sess And you will see how much these dependencies can help the more you work with FastAPI, to handle **permissions**, **authentication**, resources like database **sessions**, etc. πŸš€ -If you want to learn more about dependencies, checkout the FastAPI docs about Dependencies. +If you want to learn more about dependencies, checkout the [FastAPI docs about Dependencies](https://fastapi.tiangolo.com/tutorial/dependencies/). diff --git a/docs/tutorial/fastapi/simple-hero-api.md b/docs/tutorial/fastapi/simple-hero-api.md index 79cf075e1b..c8060ea352 100644 --- a/docs/tutorial/fastapi/simple-hero-api.md +++ b/docs/tutorial/fastapi/simple-hero-api.md @@ -8,7 +8,7 @@ The first step is to install FastAPI. FastAPI is the framework to create the **web API**. -Make sure you create a [virtual environment](../../virtual-environments.md){.internal-link target=_blank}, activate it, and then install them, for example with: +Make sure you create a [virtual environment](../../virtual-environments.md), activate it, and then install them, for example with:
@@ -42,7 +42,7 @@ And we also need to disable it because in **FastAPI** each request could be hand /// info -That's enough information for now, you can read more about it in the FastAPI docs for `async` and `await`. +That's enough information for now, you can read more about it in the [FastAPI docs for `async` and `await`](https://fastapi.tiangolo.com/async/). The main point is, by ensuring you **don't share** the same **session** with more than one request, the code is already safe. @@ -70,7 +70,7 @@ This should be called only once at startup, not before every request, so we put /// info -If you need a refresher on what a **Path Operation** is (an endpoint with a specific HTTP Operation) and how to work with it in FastAPI, check out the FastAPI First Steps docs. +If you need a refresher on what a **Path Operation** is (an endpoint with a specific HTTP Operation) and how to work with it in FastAPI, check out the [FastAPI First Steps docs](https://fastapi.tiangolo.com/tutorial/first-steps/). /// @@ -84,9 +84,9 @@ It will be called when a user sends a request with a `POST` **operation** to the If you need a refresher on some of those concepts, checkout the FastAPI documentation: -* First Steps -* Path Parameters - Data Validation and Data Conversion -* Request Body +* [First Steps](https://fastapi.tiangolo.com/tutorial/first-steps/) +* [Path Parameters - Data Validation and Data Conversion](https://fastapi.tiangolo.com/tutorial/path-params/) +* [Request Body](https://fastapi.tiangolo.com/tutorial/body/) /// @@ -132,7 +132,7 @@ But we would **never want to *share* the same session** among different requests In this simple example, we just create the new sessions manually in the **path operation functions**. -In future examples later we will use a FastAPI Dependency to get the **session**, being able to share it with other dependencies and being able to replace it during testing. πŸ€“ +In future examples later we will use a [FastAPI Dependency](https://fastapi.tiangolo.com/tutorial/dependencies/) to get the **session**, being able to share it with other dependencies and being able to replace it during testing. πŸ€“ ## Run the **FastAPI** Server in Development Mode @@ -154,7 +154,7 @@ $ fastapi dev main.py /// info -The `fastapi` command uses Uvicorn underneath. +The `fastapi` command uses [Uvicorn](https://www.uvicorn.org/) underneath. /// @@ -180,7 +180,7 @@ $ fastapi run main.py Now you can go to that URL in your browser `http://127.0.0.1:8000`. We didn't create a *path operation* for the root path `/`, so that URL alone will only show a "Not Found" error... that "Not Found" error is produced by your FastAPI application. -But you can go to the **automatically generated interactive API documentation** at the path `/docs`: http://127.0.0.1:8000/docs. ✨ +But you can go to the **automatically generated interactive API documentation** at the path `/docs`: [http://127.0.0.1:8000/docs](http://127.0.0.1:8000/docs). ✨ You will see that this **automatic API docs UI** has the *paths* that we defined above with their *operations*, and that it already knows the shape of the data that the **path operations** will receive: diff --git a/docs/tutorial/fastapi/tests.md b/docs/tutorial/fastapi/tests.md index f7fd92c9cb..7eb7e4870b 100644 --- a/docs/tutorial/fastapi/tests.md +++ b/docs/tutorial/fastapi/tests.md @@ -18,7 +18,7 @@ Now we will see how useful it is to have this session dependency. ✨ ## File Structure -Now we will have a Python project with multiple files, one file `main.py` with all the application, and one file `test_main.py` with the tests, with the same ideas from [Code Structure and Multiple Files](../code-structure.md){.internal-link target=_blank}. +Now we will have a Python project with multiple files, one file `main.py` with all the application, and one file `test_main.py` with the tests, with the same ideas from [Code Structure and Multiple Files](../code-structure.md). The file structure is: @@ -32,11 +32,11 @@ The file structure is: ## Testing FastAPI Applications -If you haven't done testing in FastAPI applications, first check the FastAPI docs about Testing. +If you haven't done testing in FastAPI applications, first check the [FastAPI docs about Testing](https://fastapi.tiangolo.com/tutorial/testing/). Then, we can continue here, the first step is to install the dependencies, `requests` and `pytest`. -Make sure you create a [virtual environment](../../virtual-environments.md){.internal-link target=_blank}, activate it, and then install them, for example with: +Make sure you create a [virtual environment](../../virtual-environments.md), activate it, and then install them, for example with:
@@ -144,7 +144,7 @@ Here we create all the tables in the testing database with: SQLModel.metadata.create_all(engine) ``` -But remember that [Order Matters](../create-db-and-table.md#sqlmodel-metadata-order-matters){.internal-link target=_blank} and we need to make sure all the **SQLModel** models are already defined and **imported** before calling `.create_all()`. +But remember that [Order Matters](../create-db-and-table.md#sqlmodel-metadata-order-matters) and we need to make sure all the **SQLModel** models are already defined and **imported** before calling `.create_all()`. In this case, it all works for a little subtlety that deserves some attention. @@ -230,7 +230,7 @@ Let's use these **fixtures** to improve our code and reduce de duplicated boiler ## Pytest Fixtures -You can read more about them in the pytest docs for fixtures, but I'll give you a short example for what we need here. +You can read more about them in the [pytest docs for fixtures](https://docs.pytest.org/en/6.2.x/fixture.html), but I'll give you a short example for what we need here. Let's see the first code example with a fixture: diff --git a/docs/tutorial/fastapi/update-extra-data.md b/docs/tutorial/fastapi/update-extra-data.md index 95843144ae..74b24d4afa 100644 --- a/docs/tutorial/fastapi/update-extra-data.md +++ b/docs/tutorial/fastapi/update-extra-data.md @@ -26,7 +26,7 @@ So, the thief won't be able to try to use that password in another system (as ma /// tip -You could use passlib to hash passwords. +You could use [passlib](https://passlib.readthedocs.io/en/stable/) to hash passwords. In this example we will use a fake hashing function to focus on the data changes. 🀑 diff --git a/docs/tutorial/index.md b/docs/tutorial/index.md index dd61e8597e..281f99081c 100644 --- a/docs/tutorial/index.md +++ b/docs/tutorial/index.md @@ -4,9 +4,9 @@ In this tutorial you will learn how to use **SQLModel**. ## Type hints -If you need a refresher about how to use Python type hints (type annotations), check FastAPI's Python types intro. +If you need a refresher about how to use Python type hints (type annotations), check [FastAPI's Python types intro](https://fastapi.tiangolo.com/python-types/). -You can also check the mypy cheat sheet. +You can also check the [mypy cheat sheet](https://mypy.readthedocs.io/en/latest/cheat_sheet_py3.html). **SQLModel** uses type annotations for everything, this way you can use a familiar Python syntax and get all the editor support possible, with autocompletion and in-editor error checking. diff --git a/docs/tutorial/many-to-many/index.md b/docs/tutorial/many-to-many/index.md index 5cb3067e4a..30ec70436d 100644 --- a/docs/tutorial/many-to-many/index.md +++ b/docs/tutorial/many-to-many/index.md @@ -128,7 +128,7 @@ I'm using the term "link table" because it's short, doesn't collide with other t ## Link Primary Key -Cool, we have a link table with **just two columns**. But remember that SQL databases [require each row to have a **primary key**](../../databases.md#identifications-primary-key){.internal-link target=_blank} that **uniquely identifies** the row in that table? +Cool, we have a link table with **just two columns**. But remember that SQL databases [require each row to have a **primary key**](../../databases.md#identifications-primary-key) that **uniquely identifies** the row in that table? Now, what is the **primary key** in this table? diff --git a/docs/tutorial/relationship-attributes/cascade-delete-relationships.md b/docs/tutorial/relationship-attributes/cascade-delete-relationships.md index 3b6fe9156c..40b6a37757 100644 --- a/docs/tutorial/relationship-attributes/cascade-delete-relationships.md +++ b/docs/tutorial/relationship-attributes/cascade-delete-relationships.md @@ -129,7 +129,7 @@ The `cascade_delete` parameter is set in the `Relationship()`, on the model that Setting `cascade_delete=True` in the `Relationship()` will configure SQLAlchemy to use `cascade="all, delete-orphan"`, which is the most common and useful configuration when wanting to cascade deletes. -You can read more about it in the SQLAlchemy docs. +You can read more about it in the [SQLAlchemy docs](https://docs.sqlalchemy.org/en/20/orm/cascades.html). /// @@ -442,7 +442,7 @@ To be able to test this out with SQLite, we first need to enable foreign key sup /// info -You can learn more about SQLite, foreign keys, and this SQL command on the SQLAlchemy docs. +You can learn more about SQLite, foreign keys, and this SQL command on the [SQLAlchemy docs](https://docs.sqlalchemy.org/en/20/dialects/sqlite.html#foreign-key-support). /// diff --git a/docs/tutorial/where.md b/docs/tutorial/where.md index 120874a235..674404bff9 100644 --- a/docs/tutorial/where.md +++ b/docs/tutorial/where.md @@ -591,7 +591,7 @@ We don't have any hero called `Ratman`, so it does not match any hero. /// tip You need to wrap your attribute with `col()` to use `in_`. -You can read more about it in the [Type annotations and errors](#type-annotations-and-errors){.internal-link target=_blank} section. +You can read more about it in the [Type annotations and errors](#type-annotations-and-errors) section. /// diff --git a/docs/virtual-environments.md b/docs/virtual-environments.md index 131cd53d76..1f19221ba0 100644 --- a/docs/virtual-environments.md +++ b/docs/virtual-environments.md @@ -22,7 +22,7 @@ A **virtual environment** is a directory with some files in it. This page will teach you how to use **virtual environments** and how they work. -If you are ready to adopt a **tool that manages everything** for you (including installing Python), try uv. +If you are ready to adopt a **tool that manages everything** for you (including installing Python), try [uv](https://github.com/astral-sh/uv). /// @@ -86,7 +86,7 @@ $ python -m venv .venv //// tab | `uv` -If you have `uv` installed, you can use it to create a virtual environment. +If you have [`uv`](https://github.com/astral-sh/uv) installed, you can use it to create a virtual environment.
@@ -150,7 +150,7 @@ $ .venv\Scripts\Activate.ps1 //// tab | Windows Bash -Or if you use Bash for Windows (e.g. Git Bash): +Or if you use Bash for Windows (e.g. [Git Bash](https://gitforwindows.org/)):
@@ -216,7 +216,7 @@ If it shows the `python` binary at `.venv\Scripts\python`, inside of your projec /// tip -If you use `uv` you would use it to install things instead of `pip`, so you don't need to upgrade `pip`. 😎 +If you use [`uv`](https://github.com/astral-sh/uv) you would use it to install things instead of `pip`, so you don't need to upgrade `pip`. 😎 /// @@ -248,7 +248,7 @@ If you are using **Git** (you should), add a `.gitignore` file to exclude everyt /// tip -If you used `uv` to create the virtual environment, it already did this for you, you can skip this step. 😎 +If you used [`uv`](https://github.com/astral-sh/uv) to create the virtual environment, it already did this for you, you can skip this step. 😎 /// @@ -320,7 +320,7 @@ $ pip install sqlmodel //// tab | `uv` -If you have `uv`: +If you have [`uv`](https://github.com/astral-sh/uv):
@@ -352,7 +352,7 @@ $ pip install -r requirements.txt //// tab | `uv` -If you have `uv`: +If you have [`uv`](https://github.com/astral-sh/uv):
@@ -396,8 +396,8 @@ You would probably use an editor, make sure you configure it to use the same vir For example: -* VS Code -* PyCharm +* [VS Code](https://code.visualstudio.com/docs/python/environments#_select-and-activate-an-environment) +* [PyCharm](https://www.jetbrains.com/help/pycharm/creating-virtual-environment.html) /// tip @@ -435,7 +435,7 @@ Continue reading. πŸ‘‡πŸ€“ ## Why Virtual Environments -To work with SQLModel you need to install Python. +To work with SQLModel you need to install [Python](https://www.python.org/). After that, you would need to **install** SQLModel and any other **packages** you want to use. @@ -544,7 +544,7 @@ $ pip install sqlmodel
-That will download a compressed file with the SQLModel code, normally from PyPI. +That will download a compressed file with the SQLModel code, normally from [PyPI](https://pypi.org/project/sqlmodel/). It will also **download** files for other packages that SQLModel depends on. @@ -607,7 +607,7 @@ $ .venv\Scripts\Activate.ps1 //// tab | Windows Bash -Or if you use Bash for Windows (e.g. Git Bash): +Or if you use Bash for Windows (e.g. [Git Bash](https://gitforwindows.org/)):
@@ -619,13 +619,13 @@ $ source .venv/Scripts/activate //// -That command will create or modify some [environment variables](environment-variables.md){.internal-link target=_blank} that will be available for the next commands. +That command will create or modify some [environment variables](environment-variables.md) that will be available for the next commands. One of those variables is the `PATH` variable. /// tip -You can learn more about the `PATH` environment variable in the [Environment Variables](environment-variables.md#path-environment-variable){.internal-link target=_blank} section. +You can learn more about the `PATH` environment variable in the [Environment Variables](environment-variables.md#path-environment-variable) section. /// @@ -826,7 +826,7 @@ This is a simple guide to get you started and teach you how everything works **u There are many **alternatives** to managing virtual environments, package dependencies (requirements), projects. -Once you are ready and want to use a tool to **manage the entire project**, packages dependencies, virtual environments, etc. I would suggest you try uv. +Once you are ready and want to use a tool to **manage the entire project**, packages dependencies, virtual environments, etc. I would suggest you try [uv](https://github.com/astral-sh/uv). `uv` can do a lot of things, it can: