[Sqlalchemy-commits] sqlalchemy: modernize the README
Brought to you by:
zzzeek
Menu
▾
▴
[Sqlalchemy-commits] sqlalchemy: modernize the README
|
From: <co...@sq...> - 2012-01-26 16:44:56
|
details: http://hg.sqlalchemy.org/sqlalchemy/sqlalchemy/rev/9dccc77f4002 changeset: 8047:9dccc77f4002 user: Mike Bayer <mi...@zz...> date: Thu Jan 26 11:44:34 2012 -0500 description: modernize the README diffstat: README | 62 ---------------------------- README.rst | 130 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ setup.py | 135 ++++-------------------------------------------------------- 3 files changed, 139 insertions(+), 188 deletions(-) diffs (truncated from 362 to 300 lines): diff -r a86e18d1de90 -r 9dccc77f4002 README --- a/README Wed Jan 25 12:49:58 2012 -0500 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,70 +0,0 @@ -SQLAlchemy -++++++++++ - -The Python SQL Toolkit and Object Relational Mapper - -Requirements ------------- - -SQLAlchemy requires Python 2.4 or higher. One or more DB-API implementations -are also required for database access. See docs/intro.html for more -information on supported DB-API implementations. - -Python 3 Compatibility ----------------------- - -Please see README.py3k for Python 3 installation and testing instructions. - -Installation Tools ------------------- - -Installation is supported with standard Python distutils, as well -as with setuptools or Distribute. Distribute is recommended. -Distribute can be installed using the provided "distribute_setup.py" -script. The original setuptools may be installed using the -"ez_setup.py" script if preferred, or simply do nothing and distutils -will be used. - -Installing ----------- - -To install:: - - python setup.py install - -To use without installation, include the ``lib`` directory in your Python -path. - -Running Tests -------------- - -Please see README.unittests for full instructions on running unit tests. - -Package Contents ----------------- - - doc/ - HTML documentation, including tutorials and API reference. Point - a browser to the "index.html" to start. - - examples/ - Fully commented and executable implementations for a variety of tasks. - - lib/ - SQLAlchemy. - - test/ - Unit tests for SQLAlchemy. - -Help ----- - -Mailing lists, wiki, and more are available on-line at -http://www.sqlalchemy.org. - -License -------- - -SQLAlchemy is distributed under the `MIT license -<http://www.opensource.org/licenses/mit-license.php>`_. - diff -r a86e18d1de90 -r 9dccc77f4002 README.rst --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/README.rst Thu Jan 26 11:44:34 2012 -0500 @@ -0,0 +1,130 @@ +SQLAlchemy +========== + +The Python SQL Toolkit and Object Relational Mapper + +Introduction +------------- + +SQLAlchemy is the Python SQL toolkit and Object Relational Mapper +that gives application developers the full power and +flexibility of SQL. SQLAlchemy provides a full suite +of well known enterprise-level persistence patterns, +designed for efficient and high-performing database +access, adapted into a simple and Pythonic domain +language. + +Major SQLAlchemy features include: + +* An industrial strength ORM, built + from the core on the identity map, unit of work, + and data mapper patterns. These patterns + allow 100% of object persistence behavior to + be defined declaratively. The domain model + can be constructed and manipulated naturally, + and changes are synchronized with the + current transaction automatically. +* A relationally-oriented query system, exposing + joins, subqueries, correlation, and everything + else explicitly, in terms of the object model. + Writing queries with the ORM uses the same + techniques of relational composition you use + when writing SQL. While you can drop into + literal SQL at any time, it's virtually never + needed. +* The most comprehensive and flexible system anywhere + of eager loading of related collections and objects. + Collections are fully cached within a session, + and can be loaded on individual access, all + at once using joins, or by query per collection + across the full result set. +* A Core SQL construction system and DBAPI + interaction layer. The SQLAlchemy Core is + separate from the ORM and is a full database + abstraction layer in it's own right, and includes + an extensible Python-based SQL expression + language, schema metadata, connection pooling, + type coercion, and custom types. +* All primary and foreign key constraints are + assumed to be composite and natural. Surrogate + integer primary keys are of course still the + norm, but SQLAlchemy never assumes or hardcodes + to this model. +* Database introspection and generation. Database + schemas can be "reflected" in one step into + Python structures representing database metadata; + those same structures can then generate + CREATE statements right back out - all within + the Core, independent of the ORM. + +SQLAlchemy's philosophy: + +* SQL databases behave less and less like object + collections the more size and performance start to + matter; object collections behave less and less like + tables and rows the more abstraction starts to matter. + SQLAlchemy aims to accommodate both of these + principles. +* An ORM doesn't need to hide the "R". A relational + database provides rich, set-based functionality + that should be fully exposed. SQLAlchemy's + ORM provides an open-ended set of patterns + that allow a developer to construct a custom + mediation layer between a domain model and + a relational schema, turning the so-called + "object relational impedance" issue into + a distant memory. +* The developer, in all cases, makes all decisions + regarding the design, structure, and naming conventions + of both the object model as well as the relational + schema. SQLAlchemy only provides the means + to automate the execution of these decisions. +* With SQLAlchemy, there's no such thing as + "the ORM generated a bad query" - you + retain full control over the structure of + queries, including how joins are organized, + how subqueries and correlation is used, what + columns are requested. +* Don't use an ORM if the problem doesn't need one. + SQLAlchemy consists of a Core and separate ORM + component. The Core offers a full SQL expression + language that allows Pythonic construction + of SQL constructs that render directly to SQL + strings for a target database, returning + result sets that are essentially enhanced DBAPI + cursors. +* Transactions should be the norm. With SQLAlchemy's + ORM, nothing goes to permanent storage until + commit() is called. SQLAlchemy encourages applications + to create a consistent means of delineating + the start and end of a series of operations. +* Never render a literal value in a SQL statement. + Bound parameters are used to the greatest degree + possible, allowing query optimizers to cache + query plans effectively, to make SQL injection + attacks a non-issue. + +Documentation +------------- + +Latest documentation is at: + +http://www.sqlalchemy.org/docs/ + +Installation / Requirements +--------------------------- + +Full documentation for installation is at +`Installation <http://www.sqlalchemy.org/docs/intro.html#installation>`_. + +Getting Help / Development / Bug reporting +------------------------------------------ + +Please refer to the `SQLAlchemy Community Guide <http://www.sqlalchemy.org/support.html>`_. + +License +------- + +SQLAlchemy is distributed under the `MIT license +<http://www.opensource.org/licenses/mit-license.php>`_. + diff -r a86e18d1de90 -r 9dccc77f4002 setup.py --- a/setup.py Wed Jan 25 12:49:58 2012 -0500 +++ b/setup.py Thu Jan 26 11:44:34 2012 -0500 @@ -101,11 +101,16 @@ packages.append(fragment.replace(os.sep, '.')) return packages -v = open(os.path.join(os.path.dirname(__file__), +v_file = open(os.path.join(os.path.dirname(__file__), 'lib', 'sqlalchemy', '__init__.py')) VERSION = re.compile(r".*__version__ = '(.*?)'", - re.S).match(v.read()).group(1) -v.close() + re.S).match(v_file.read()).group(1) +v_file.close() + +r_file = open(os.path.join(os.path.dirname(__file__), 'README.rst')) +readme = r_file.read() +r_file.close() + def run_setup(with_cext): kwargs = extra.copy() @@ -132,129 +137,7 @@ tests_require=['nose >= 0.11'], test_suite="sqla_nose", - - long_description="""\ - SQLAlchemy is: - - * The Python SQL toolkit and Object Relational Mapper - that gives application developers the full power and - flexibility of SQL. SQLAlchemy provides a full suite - of well known enterprise-level persistence patterns, - designed for efficient and high-performing database - access, adapted into a simple and Pythonic domain - language. - * extremely easy to use for all the basic tasks, such - as: accessing pooled connections, constructing SQL - from Python expressions, finding object instances, and - commiting object modifications back to the database. - * powerful enough for complicated tasks, such as: eager - load a graph of objects and their dependencies via - joins; map recursive adjacency structures - automatically; map objects to not just tables but to - any arbitrary join or select statement; combine - multiple tables together to load whole sets of - otherwise unrelated objects from a single result set; - commit entire graphs of object changes in one step. - * built to conform to what DBAs demand, including the - ability to swap out generated SQL with hand-optimized - statements, full usage of bind parameters for all - literal values, fully transactionalized and consistent - updates using Unit of Work. - * modular. Different parts of SQLAlchemy can be used - independently of the rest, including the connection - pool, SQL construction, and ORM. SQLAlchemy is - constructed in an open style that allows plenty of - customization, with an architecture that supports - custom datatypes, custom SQL extensions, and ORM - plugins which can augment or extend mapping - functionality. - - SQLAlchemy's Philosophy: - - * SQL databases behave less and less like object - collections the more size and performance start to - matter; object collections behave less and less like - tables and rows the more abstraction starts to matter. - SQLAlchemy aims to accomodate both of these - principles. - * Your classes aren't tables, and your objects aren't - rows. Databases aren't just collections of tables; - they're relational algebra engines. You don't have to - select from just tables, you can select from joins, - subqueries, and unions. Database and domain concepts - should be visibly decoupled from the beginning, - allowing both sides to develop to their full - potential. - * For example, table metadata (objects that describe - tables) are declared distinctly from the classes - theyre designed to store. That way database - relationship concepts don't interfere with your object - design concepts, and vice-versa; the transition from - table-mapping to selectable-mapping is seamless; a - class can be mapped against the database in more than - one way. SQLAlchemy provides a powerful mapping layer - that can work as automatically or as manually as you - choose, determining relationships based on foreign - keys or letting you define the join conditions - explicitly, to bridge the gap between database and |