55 :target: https://coveralls.io/github/agronholm/sqlacodegen?branch=master
66 :alt: Code Coverage
77
8- This is a tool that reads the structure of an existing database and generates the appropriate
9- SQLAlchemy model code, using the declarative style if possible.
8+ This is a tool that reads the structure of an existing database and generates the
9+ appropriate SQLAlchemy model code, using the declarative style if possible.
1010
11- This tool was written as a replacement for `sqlautocode `_, which was suffering from several issues
12- (including, but not limited to, incompatibility with Python 3 and the latest SQLAlchemy version).
11+ This tool was written as a replacement for `sqlautocode `_, which was suffering from
12+ several issues (including, but not limited to, incompatibility with Python 3 and the
13+ latest SQLAlchemy version).
1314
1415.. _sqlautocode : http://code.google.com/p/sqlautocode/
1516
@@ -34,18 +35,18 @@ To install, do::
3435
3536 pip install sqlacodegen
3637
37- To include support for the PostgreSQL ``CITEXT `` extension type (which should be considered as
38- tested only under a few environments) specify the ``citext `` extra::
38+ To include support for the PostgreSQL ``CITEXT `` extension type (which should be
39+ considered as tested only under a few environments) specify the ``citext `` extra::
3940
4041 pip install sqlacodegen[citext]
4142
4243
4344Quickstart
4445==========
4546
46- At the minimum, you have to give sqlacodegen a database URL. The URL is passed directly to
47- SQLAlchemy's `create_engine() `_ method so please refer to ` SQLAlchemy's documentation `_ for
48- instructions on how to construct a proper URL.
47+ At the minimum, you have to give sqlacodegen a database URL. The URL is passed directly
48+ to SQLAlchemy's `create_engine() `_ method so please refer to
49+ ` SQLAlchemy's documentation `_ for instructions on how to construct a proper URL.
4950
5051Examples::
5152
@@ -74,8 +75,8 @@ The following built-in generators are available:
7475Generator-specific options
7576==========================
7677
77- The following options can be turned on by passing them using ``--option `` (can be used multiple
78- times):
78+ The following options can be turned on by passing them using ``--option `` (can be used
79+ multiple times):
7980
8081* ``tables ``
8182
@@ -89,8 +90,9 @@ times):
8990 * ``use_inflect ``: use the ``inflect `` library when naming classes and relationships
9091 (turning plural names into singular; see below for details)
9192 * ``nojoined ``: don't try to detect joined-class inheritance (see below for details)
92- * ``nobidi ``: generate relationships in a unidirectional fashion, so only the many-to-one
93- or first side of many-to-many relationships gets a relationship attribute, as on v2.X
93+ * ``nobidi ``: generate relationships in a unidirectional fashion, so only the
94+ many-to-one or first side of many-to-many relationships gets a relationship
95+ attribute, as on v2.X
9496
9597* ``dataclasses ``
9698
@@ -99,35 +101,40 @@ times):
99101Model class generators
100102----------------------
101103
102- The code generators that generate classes try to generate model classes whenever possible.
103- There are two circumstances in which a ``Table `` is generated instead:
104+ The code generators that generate classes try to generate model classes whenever
105+ possible. There are two circumstances in which a ``Table `` is generated instead:
104106
105- * the table has no primary key constraint (which is required by SQLAlchemy for every model class)
106- * the table is an association table between two other tables (see below for the specifics)
107+ * the table has no primary key constraint (which is required by SQLAlchemy for every
108+ model class)
109+ * the table is an association table between two other tables (see below for the
110+ specifics)
107111
108112Model class naming logic
109113++++++++++++++++++++++++
110114
111- By default, table names are converted to valid PEP 8 compliant class names by replacing all
112- characters unsuitable for Python identifiers with ``_ ``. Then, each valid parts (separated by
113- underscores) are title cased and then joined together, eliminating the underscores. So,
114- ``example_name `` becomes ``ExampleName ``.
115+ By default, table names are converted to valid PEP 8 compliant class names by replacing
116+ all characters unsuitable for Python identifiers with ``_ ``. Then, each valid parts
117+ (separated by underscores) are title cased and then joined together, eliminating the
118+ underscores. So, ``example_name `` becomes ``ExampleName ``.
115119
116- If the ``use_inflect `` option is used, the table name (which is assumed to be in English) is
117- converted to singular form using the "inflect" library. For example, ``sales_invoices `` becomes
118- ``SalesInvoice ``. Since table names are not always in English, and the inflection process is far
119- from perfect, inflection is disabled by default.
120+ If the ``use_inflect `` option is used, the table name (which is assumed to be in
121+ English) is converted to singular form using the "inflect" library. For example,
122+ ``sales_invoices `` becomes ``SalesInvoice ``. Since table names are not always in
123+ English, and the inflection process is far from perfect, inflection is disabled by
124+ default.
120125
121126Relationship detection logic
122127++++++++++++++++++++++++++++
123128
124129Relationships are detected based on existing foreign key constraints as follows:
125130
126131* **many-to-one **: a foreign key constraint exists on the table
127- * **one-to-one **: same as **many-to-one **, but a unique constraint exists on the column(s) involved
132+ * **one-to-one **: same as **many-to-one **, but a unique constraint exists on the
133+ column(s) involved
128134* **many-to-many **: an association table is found to exist between two tables
129135
130- A table is considered an association table if it satisfies all of the following conditions:
136+ A table is considered an association table if it satisfies all of the following
137+ conditions:
131138
132139#. has exactly two foreign key constraints
133140#. all its columns are involved in said constraints
@@ -136,26 +143,27 @@ Relationship naming logic
136143+++++++++++++++++++++++++
137144
138145Relationships are typically named based on the table name of the opposite class.
139- For example, if a class has a relationship to another class with the table named ``companies ``, the
140- relationship would be named ``companies `` (unless the ``use_inflect `` option was enabled, in which
141- case it would be named ``company `` in the case of a many-to-one or one-to-one relationship).
146+ For example, if a class has a relationship to another class with the table named
147+ ``companies ``, the relationship would be named ``companies `` (unless the ``use_inflect ``
148+ option was enabled, in which case it would be named ``company `` in the case of a
149+ many-to-one or one-to-one relationship).
142150
143- A special case for single column many-to-one and one-to-one relationships, however, is if the
144- column is named like ``employer_id ``. Then the relationship is named ``employer `` due to that
145- ``_id `` suffix.
151+ A special case for single column many-to-one and one-to-one relationships, however, is
152+ if the column is named like ``employer_id ``. Then the relationship is named ``employer ``
153+ due to that ``_id `` suffix.
146154
147- For self referential relationships, the reverse side of the relationship will be named with the
148- ``_reverse `` suffix appended to it.
155+ For self referential relationships, the reverse side of the relationship will be named
156+ with the ``_reverse `` suffix appended to it.
149157
150158Customizing code generation logic
151159=================================
152160
153- If the built-in generators with all their options don't quite do what you want, you can customize
154- the logic by subclassing one of the existing code generator classes. Override whichever methods
155- you need, and then add an `entry point `_ in the `` sqlacodegen.generators `` namespace that points
156- to your new class. Once the entry point is in place (you typically have to install the project with
157- `` pip install ``), you can use `` --generator <yourentrypoint> `` to invoke your custom code
158- generator.
161+ If the built-in generators with all their options don't quite do what you want, you can
162+ customize the logic by subclassing one of the existing code generator classes. Override
163+ whichever methods you need, and then add an `entry point `_ in the
164+ `` sqlacodegen.generators `` namespace that points to your new class. Once the entry point
165+ is in place ( you typically have to install the project with `` pip install ``), you can
166+ use `` --generator <yourentrypoint> `` to invoke your custom code generator.
159167
160168For examples, you can look at sqlacodegen's own entry points in its `setup.cfg `_.
161169
0 commit comments