--- /dev/null
+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>`_.
+
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()
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",
projects / thirdparty / sqlalchemy / sqlalchemy.git / commitdiff
