aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--readme.md53
1 files changed, 53 insertions, 0 deletions
diff --git a/readme.md b/readme.md
index b5844f2..6fab8d8 100644
--- a/readme.md
+++ b/readme.md
@@ -110,6 +110,59 @@ of annotated raw SQL queries, exposing them as callable Python functions.
110[embrace]: https://pypi.org/project/embrace/ 110[embrace]: https://pypi.org/project/embrace/
111[DAO]: https://en.wikipedia.org/wiki/Data_access_object 111[DAO]: https://en.wikipedia.org/wiki/Data_access_object
112 112
113#### CGI scripts vs. Services
114
115The most simple and primitive way of making Python programs accessible from a
116web browser would be through the Common Gateway Interface ([CGI]). Through it,
117the user is able to execute the scripts by visiting a matching URL, to then
118visualise its output directly in their browser.
119
120[CGI]: https://en.wikipedia.org/wiki/Common_Gateway_Interface
121
122The other approach is to make the program a server application as a persistent
123service process, in charge of accepting, handling and replying to network
124requests by itself.
125
126The former, identical to the way the oldest PHP scripts are run, has become
127less popular in favour of the latter, mainly for performance and
128maintainability concerns for real applications outside of trivial, independent,
129and self-contained scripts. For those reasons, this project will be implemented
130as a service process.
131
132#### Comprehensive vs. Light-weight frameworks
133
134While bare Python could be used to create such a web service, it is desirable
135to work at a higher abstraction level to focus on the application-specific
136features rather than the standard protocol implementation details.
137
138Python frameworks such as [Django] offer comprehensive solutions for building
139web applications based on the Model-View-Controller ([MVC] or MTV/MVT) design
140pattern, ensuring [separation of concerns] while abstracting lower level logic.
141This kind of complete solutions provide routing logic to map requests to
142user-defined handlers, and are integrated with a Object-Relational Mapper as
143well as with a templating engine to generate HTML pages dynamically.
144
145[Django]: https://www.djangoproject.com/
146[MVC]: https://en.wikipedia.org/wiki/Model-view-controller
147[separation of concerns]: https://en.wikipedia.org/wiki/Separation_of_concerns
148
149Other more light-weight frameworks such as [Flask] or the more recent [FastAPI]
150instead focus on the first part, taking care of unpacking and routing requests
151to the user-defined handlers, while leaving the rest to the application
152developers. This approach does not fully impose an entire environment, and
153allows better composability with libraries which can be freely chosen.
154
155[Flask]: https://flask.palletsprojects.com/
156[FastAPI]: https://fastapi.tiangolo.com/
157
158Because the use of an ORM is not desirable in this project for the reasons
159detailed in a previous section, the choices of frameworks is limited to these
160light-weight frameworks. Here, FastAPI is preferred over Flask due to its more
161modern architecture, using parameters and [dependency injection] over
162thread-local global variables.
163
164[dependency injection]: https://en.wikipedia.org/wiki/Dependency_injection
165
113### Project structure overview 166### Project structure overview
114 167
115* `./sql/` 168* `./sql/`