Porm Documentation Release 0.0

Home , SQLAlchemy, Storm (software)

José Manuel González del Campo

Dec 25, 2017

Contents

1 Enter Porm 1

2 Why Porm? 3

3 Project status 5

4 Documentation 7

5 License 9

i ii CHAPTER 1

Enter Porm

Porm is an Object Relational Mapper for Python with a focus in performance. It derives from the Storm ORM originally developed by Canonical. The development of Storm-ORM was stalled since year 2013, and the last version was only compatible with Python 2. This is an efort to resurrect the project and to give it an actualised, modern and cozy new home in GitHub and Read the Docs. I believe that the project deserves it, as it was one of the most performance focused ORM that python had and, furthermore, it has been very tested in production, being used in Launchpad, among other Canonical projects.

1 Porm Documentation, Release 0.0

2 Chapter 1. Enter Porm CHAPTER 2

Why Porm?

You may know that there are already several ORM, being probably SQLAlchemy and Peewee the most recognized among them. So, the first and obvious question is: why Porm? I don’t want to make here a marketing exercice, but to build a transparent source of information. The main reason I took the work of rescuing, evolving and mantaining Porm because I needed an ORM to use in a project, and when I looked, I came to the conclusion that the most supported and documented were the two mentioned ORMs. But SQLAlchemy was an overkill, and I found that the performance was nothing to shout about, and the codebase size didn’t allowed me to take a glance of what was happening behind scenes in a reasonable amount of time (you may argue that it would take me less time that this effort, but it would be less exciting, at least for me). Then I looked at Peewee. I have to recognize that I feel admiration for the project, it has a lean one-file (plus extensions) codebase, a great documentation, full support to almost anything you may want and a super easy API to work with. But, although it counts with a bunch of lines of cython optimization, I was almost certain that something more could be done. And then I found the Storm ORM, an old project by Canonical, implemented in Python 2, and that was used by the company in all of its projects. The codebase looked clean, and although I realized that it lacked some functionality that I had found in Peewee and that I would like to have, when I could have turned and start to work with Peewee I had already half the Storm codebase translated, and I was very familiar with it. One of the things I liked the most, and that was of paramount importance for me to decide, was the size of the pure C optimization code and its quality. So, I decided to commit myself not only to translate and mantain it, but also to try to improve it where I can. • Porm is fast, thanks to its extension writen in pure C. • Its clean and lightweight API offers a short learning curve and long-term maintainability. • Porm is developed in a test-driven manner. An untested line of code is considered a bug. This means: ~14.000 app LOC vs. 22.000 tests code. • Porm needs no special class constructors, nor imperative base classes. • It’s very easy to write and support backends for Porm (current backends have around 100 lines of code). • Porm handles relationships between objects even before they were added to a database, functioning with a cache system that improves performance (at least in theory and where network connections are needed). • Porm will flush changes to the database automatically when needed, so that queries made affect recently modi- fied objects.

3 Porm Documentation, Release 0.0

• Porm can handle obj.attr = A SQL expression assignments, when that’s really needed (the expression is executed at INSERT/UPDATE time). • Porm allows you to fallback to SQL if needed (or if you just prefer), allowing you to mix “old school” code and ORM code. • Porm handles composed primary keys with ease (no need for surrogate keys).

4 Chapter 2. Why Porm? CHAPTER 3

Project status

The current version is the 0.3 and, at until the releasement of the version 0.4, Porm has a beta status. That means that it could be some loose end here and there, and that there are some modules that doesn’t work completely. However, Porm takes a test oriented development approach (inheritated from the original Storm ORM project), under which every line of code is tested with very very few exceptions. The code released as 0.3 was passing all the unit tests. So, what are those loose ends I was talking about? Well, check it out: • The MySQL and PosgreSQL have been translated to Python 3 and pass all the necessary tests, but there have not been other checks to determine backend compatibility (and the last actualization of Storm ORM was five years ago). So, it may happen that some new functionalities are not supported, or that changes in the underlying drivers have broken the functioning with these databases (SQLite is fully tested and actualized, however). • The documentation is not complete. Apart of the API automatically generated documentation and the tutorial (which are complete), the rest of the documentation is currently in the making, so you may find some challenges finding answers. In any case, you can communicate with me directly a through the github page. Just open an issue. • The situation of django integration has similar problems to those of the MySQL and PosgreSQL backends. It passes the tests, but it’s not tested with the current Django API. • There is not integration with falsk yet, nor any other web framework.

5 Porm Documentation, Release 0.0

6 Chapter 3. Project status CHAPTER 4

Documentation

As stated, the main source of information is this tutorial, and although the manual is not ready yet, you may ﬁnd there already what you are looking. Other useful links are: • The module structure: something you may want to look before looking the API or the code. • The API documentation • Infoheritance: a common Porm design pattern. • The FAQ • The roadmap • Contributing guidelines • The code.

7 Porm Documentation, Release 0.0

8 Chapter 4. Documentation CHAPTER 5

License

DISTRIBUTED UNDER THE GNU LESSER GENERAL PUBLIC LICENSE V 2.1 This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2.1 of the License, or (at your option) any later version. This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details. You should have received a copy of the GNU Lesser General Public License along with this library; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA Note: the original project had a clause whereby “all contributions must have copyright assigned to Canonical”. Obvi- ously, that’s not longer required. You can ﬁnd its full text here.

Note: My ﬁrst language is not English, and that may be depicted with more or less intensity along the documentation, depending on how much inspired and focused I am at the moment of writing. If you, during lecture, feel aggrieved for a neglected and maybe insulting use of the English language and you have some spare time, please, it would be highly appreciated if you could issue a pull request to ﬁx all the problems you have detected.