LADI
/
py-sqlalchemy
1
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

modernize the README

This commit is contained in:
Mike Bayer 2012-01-26 11:44:34 -05:00
parent dfb0b6aa62
commit 6d333bc5a8
3 changed files with 139 additions and 196 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

70
README
View File

@ -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>`_.

130
README.rst Normal file
View File

@ -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>`_.

135
setup.py
View File

@ -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",