From: Mike Bayer Date: Thu, 26 Jan 2012 16:44:34 +0000 (-0500) Subject: modernize the README X-Git-Tag: rel_0_7_5~24 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=6d333bc5a8fb53bee244a33d09a5032b723c2745;p=thirdparty%2Fsqlalchemy%2Fsqlalchemy.git modernize the README --- diff --git a/README b/README deleted file mode 100644 index f3d67529ae..0000000000 --- a/README +++ /dev/null @@ -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 -`_. - diff --git a/README.rst b/README.rst new file mode 100644 index 0000000000..0ba17e00f9 --- /dev/null +++ b/README.rst @@ -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 `_. + +Getting Help / Development / Bug reporting +------------------------------------------ + +Please refer to the `SQLAlchemy Community Guide `_. + +License +------- + +SQLAlchemy is distributed under the `MIT license +`_. + diff --git a/setup.py b/setup.py index a0b91356b9..94ab90278f 100644 --- a/setup.py +++ b/setup.py @@ -101,11 +101,16 @@ def find_packages(dir_): 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 @@ def run_setup(with_cext): 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 - domain. - - SQLAlchemy's Advantages: - - * The Unit Of Work system organizes pending CRUD - operations into queues and commits them all in one - batch. It then performs a topological "dependency - sort" of all items to be committed and deleted and - groups redundant statements together. This produces - the maxiumum efficiency and transaction safety, and - minimizes chances of deadlocks. Modeled after Fowler's - "Unit of Work" pattern as well as Java Hibernate. - * Function-based query construction allows boolean - expressions, operators, functions, table aliases, - selectable subqueries, create/update/insert/delete - queries, correlated updates, correlated EXISTS - clauses, UNION clauses, inner and outer joins, bind - parameters, free mixing of literal text within - expressions, as little or as much as desired. - Query-compilation is vendor-specific; the same query - object can be compiled into any number of resulting - SQL strings depending on its compilation algorithm. - * Database mapping and class design are totally - separate. Persisted objects have no subclassing - requirement (other than 'object') and are POPO's : - plain old Python objects. They retain serializability - (pickling) for usage in various caching systems and - session objects. SQLAlchemy "decorates" classes with - non-intrusive property accessors to automatically log - object creates and modifications with the UnitOfWork - engine, to lazyload related data, as well as to track - attribute change histories. - * Custom list classes can be used with eagerly or lazily - loaded child object lists, allowing rich relationships - to be created on the fly as SQLAlchemy appends child - objects to an object attribute. - * Composite (multiple-column) primary keys are - supported, as are "association" objects that represent - the middle of a "many-to-many" relationship. - * Self-referential tables and mappers are supported. - Adjacency list structures can be created, saved, and - deleted with proper cascading, with no extra - programming. - * Data mapping can be used in a row-based manner. Any - bizarre hyper-optimized query that you or your DBA can - cook up, you can run in SQLAlchemy, and as long as it - returns the expected columns within a rowset, you can - get your objects from it. For a rowset that contains - more than one kind of object per row, multiple mappers - can be chained together to return multiple object - instance lists from a single database round trip. - * The type system allows pre- and post- processing of - data, both at the bind parameter and the result set - level. User-defined types can be freely mixed with - built-in types. Generic types as well as SQL-specific - types are available. - - """, + long_description=readme, classifiers=[ "Development Status :: 5 - Production/Stable", "Intended Audience :: Developers",