Mike Bayer [Fri, 11 Mar 2022 21:01:09 +0000 (16:01 -0500)]
further simplify pool-sharing doc
1. the event based approach doesn't require dispose() to be
called at all, and the note that the "pool will hang" makes
no sense. I have no idea what that refers towards
2. the subsequent paragraph about connections and sessions
is unintelligible. old paragraphs like these are likely
why people complain about the docs so much. try to just
say "don't do this", as that is easier than trying to
explain to use connection.invalidate() etc.
Mike Bayer [Fri, 11 Mar 2022 18:40:16 +0000 (13:40 -0500)]
add copybutton
works great, including for plain code plus prompt code
with SQL (copies only the prompt code when prompts are present).
added some styling to zzzeeksphinx
Mike Bayer [Sun, 12 Apr 2020 19:18:02 +0000 (15:18 -0400)]
Enable zzzeeksphinx module prefixes
zzzeeksphinx 1.1.2 in git can now convert short
prefix names in a configured lookup to fully qualified module
names, so that
we can have succinct and portable pyrefs
that still resolve absolutely.
It also includes a formatter that will format all pyrefs
in a fully consistent way regardless of the package path,
by unconditionally removing all package tokens but always
leaving class names in place including for methods, which
means we no longer have to deal with tildes in pyrefs.
The most immediate goal of the absolute prefixes is
that we have lots of
"ambiguous" names that appear in muliple places, like select(),
ARRAY, ENUM etc. With the incoming future packages there
is going to be lots of name overlap so it is necessary
that all names eventually use absolute package paths
when Sphinx receives them.
In multiple stages, pyrefs will be converted using the
zzzeeksphinx tools/fix_xrefs.py tool so that doclinks can
be made absolute using symbolic prefixes.
For this review, the actual search and replace of symbols
is not performed, instead some general cleanup to prepare
the docs as well as a lookup file used by the tool
to do the conversion. this relatively small patch will
be backported
with appropriate changes to 1.3, 1.2, 1.1 and the tool
can then be run on each branch individually. We are shooting
for almost no warnings at all for master (still a handful
I can't figure out which don't seem to have any impact)
, very few for 1.3,
and for 1.2 / 1.1 we hope for a significant reduction
in warnings.
Overall for all versions pyrefs should
always point to the correct target, if they are in fact
hyperlinked. it's better for a ref to go nowhere and
be plain text than go to the wrong thing. Right now,
hundreds of API links are pointing to the wrong thing
as they are ambiguous names such as refresh(), insert(),
update(), select(), join(), JSON etc. and Sphinx sends these all
to essesntially random destinations among as many as five
or six possible choices per symbol. A shorthand system
that allows us to use absolute refs without having
to type out a full blown absoulte module is the only
way this is going to work, and we should ultimately
seek to abandon any use of prefix dot for lookups. Everything
should be on an underscore token so at the very least the module
spaces can be reorganized without having to search and replace
the entire documentation every time.
Mike Bayer [Fri, 20 Mar 2020 20:40:47 +0000 (16:40 -0400)]
Clarify Alembic vs. Migrate
Migrate is fully legacy at this point so continue to mention
it to provide clarity, but ensure it isn't suggested
as a real alternative. It's unclear if Migrate will be able
to support SQLAlchemy 2.0.
Mike Bayer [Mon, 2 Mar 2020 15:28:32 +0000 (10:28 -0500)]
Update dialect API documentation
The docstrings for connect() and on_connect() were incorrect
between Dialect vs. DefaultDialect. Redocumented related
methods, clean up formatting, and remove unicode-related
attribute descriptions from the top level Dialect document
as these don't apply to Python 3.
Albert Tugushev [Wed, 26 Feb 2020 16:09:29 +0000 (11:09 -0500)]
Remove print statement in favor of print() function in docs and examples
<!-- Provide a general summary of your proposed changes in the Title field above -->
### Description
<!-- Describe your changes in detail -->
Remove print statements
### Checklist
<!-- go over following points. check them with an `x` if they do apply, (they turn into clickable checkboxes once the PR is submitted, so no need to do everything at once)
-->
This pull request is:
- [X] A documentation / typographical error fix
- Good to go, no issue or tests are needed
- [ ] A short code fix
- please include the issue number, and create an issue if none exists, which
must include a complete example of the issue. one line code fixes without an
issue and demonstration will not be accepted.
- Please include: `Fixes: #<issue number>` in the commit message
- please include tests. one line code fixes without tests will not be accepted.
- [ ] A new feature implementation
- please include the issue number, and create an issue if none exists, which must
include a complete example of how the feature would look.
- Please include: `Fixes: #<issue number>` in the commit message
- please include tests.
Mike Bayer [Thu, 13 Feb 2020 17:48:26 +0000 (12:48 -0500)]
Improve ResultProxy/Row documentation before the API change
We'd like to merge Ieb9085e9bcff564359095b754da9ae0af55679f0,
however the documentation in that change should be based off
of more comprehensive documentation than what we have already.
Add the notion of "row" to the tutorial and document all
methods. This will also be backported at least to 1.3
in terms of RowProxy.
Mike Bayer [Thu, 6 Feb 2020 15:26:50 +0000 (10:26 -0500)]
Document SQLite "mixed binary" behavior
The Pysqlite driver can store a string value with
or without an indicator that the value is to be retrieved
as bytes or as a unicode string object. To suit the
use case where a SQLite database has mixed values on a row
by row basis, provide a recipe for a MixedBinary datatype.
Mike Bayer [Tue, 4 Feb 2020 21:46:49 +0000 (16:46 -0500)]
Add second section detailing cascade_backrefs to backref section
We only have docs for "cascade_backrefs" in the session->cascades
documentation, when this really should be mentioned in the chapter
that's all about backrefs. Add a similar section and link to the
original for further detail.
Mike Bayer [Tue, 31 Dec 2019 01:01:23 +0000 (20:01 -0500)]
Fix newly found rst issue
Likely due to new versions flake8-rst-docstrings or similar,
repair an incorrectly formatted code example in a doc string
causing all the gerrits to fail.
Mike Bayer [Thu, 19 Dec 2019 14:19:53 +0000 (09:19 -0500)]
Improve documentation for refresh_flush event
This event does not include INSERTed primary key columns
and additionally will always be limited to default/onupdate
columns. Note better choices for interception of INSERT
events.
Mike Bayer [Thu, 31 Oct 2019 14:30:46 +0000 (10:30 -0400)]
Improve SQL Server pyodbc documentation
While we were told years ago that ODBC is intended to be used with
DSNs only, however this use does not correspond well with how most
other database connectivity systems work in that modern systems
already have their own registries of connection information in any
case, meaning this is usually the best place to add details such
as hostnames and driver names, rather than having them locked away
in a server-specific ODBC registry. So here we dial back the
language that one style or another of connecting is "preferred";
both styles are supported equally, and the critical advantage of
hostname mapping in that the target database name is both explicit
as well as modifyable is also added.
Add additional background for how DSNs work and refine other
sentences. "URL encoding" is the correct terminology for
adding spaces and special characters to a URL.
Mike Bayer [Fri, 25 Oct 2019 14:08:18 +0000 (10:08 -0400)]
Warn that before_compile for lazyload needs bake_queries=False
The longer term future plan for ORM queries is that there
will be a new hook that receives queries before invocation
rather than "compilation", which will make use of a new
caching system.
Mike Bayer [Wed, 23 Oct 2019 15:18:56 +0000 (11:18 -0400)]
Add doc note for multiple table mapping
When mapping to a construct like OUTER JOIN, an UPDATE from the
ORM expects that all involved tables have a row already present;
document this as well as a potential workaround.
In 14b1e6fe8e18d139846c1aba6761d4eea3dc25c3 we added
suite-level requirements but did not add them to the
base, causing failures in third party dialect test suites.
Mike Bayer [Wed, 18 Sep 2019 01:04:21 +0000 (21:04 -0400)]
Add missing suite level requirements from 2efd89d02941
In 2efd89d02941ab4267d6e2842963fd38b1539f6c we added
suite-level requirements but did not add them to the
base, causing failures in third party dialect test suites.
Mike Bayer [Tue, 17 Sep 2019 16:49:46 +0000 (12:49 -0400)]
Add missing suite level requirements from #4234
In 9d5e117f6fcc38d8773bc943c615888dc8a3a819 we added
suite-level requirements but did not add them to the
base, causing failures in third party dialect test suites.
Mike Bayer [Thu, 12 Sep 2019 16:37:38 +0000 (12:37 -0400)]
Document visitors module
As we are going to be adding a lot of new features to the visitors
module which may impact end-user custom constructs, start documenting
the package for now.
Mike Bayer [Thu, 5 Sep 2019 15:46:44 +0000 (11:46 -0400)]
Document Query deduplication
Users are frequently confused why count() does not return the same
number as the number of objects returned by all(). While we continue
to want to find a better solution to this problem, in the meantime
this has never been clearly documented. Add an FAQ section with
links from .count() , .all(), ORM tutorial.
Mike Bayer [Tue, 20 Aug 2019 13:42:36 +0000 (09:42 -0400)]
Document how to work with reflection and custom datatypes
Describe the link between table reflection, datatype lookups,
and what approaches are needed in the case where in-Python datatypes
are needed in the reflected table metadata.
Mike Bayer [Sat, 10 Aug 2019 22:17:59 +0000 (18:17 -0400)]
Clarify INSERT/UPDATE defaults vs. data marshalling
- Add a full introductory paragraph to INSERT/UPDATE defaults
stating what we mean when we talk about this concept. Add a note
differentiating what a default does, vs. a rule that intercepts
data as it moves into the database, providing links
- Add a quick section referring to TypeDecorator in the ORM
section on modifying attribute behavior
- Add an "ORM tip", a new thing that we can use in Core to link
to ORM concepts when useful, in the TypeDecorator section which
mentions that for more open ended conversion of arbitrary user
data based on business rules, @validates might be useful
(although this still does not suit the case of full blown form
validation).
- add glossary entries for DML, data marshalling since we already
use these terms and I'd like to refer to them more often.
Mike Bayer [Fri, 5 Jul 2019 16:19:55 +0000 (12:19 -0400)]
Note DBAPIs and dialects that we don't support
Since we have strong CI for the DBAPIs and dialects that are actively
supported, this indicates that those DBAPIs that aren't in CI are
continuing to fall behind in support, to the point where we can
not address issues that may arise. As such, the Sybase and Firebird
dialects overall are moving into an explicit "not supported" zone
where we would like to eventually remove them. Additionally,
a pass is made through legacy MySQL and PostgreSQL DBAPI dialects
as well as those which we aren't able to include in CI to note
that these DBAPIs aren't actively supported by the project.
Mike Bayer [Fri, 7 Jun 2019 18:50:22 +0000 (14:50 -0400)]
Rework Session transaction FAQs
In preparation for #4712, add an errors.rst code to the Session's
exception about waiting to be rolled back and rework the FAQ entry
to be much more succinct. When this FAQ was first written, I found
it hard to describe why flush worked this way but as the use case is
clearer now, and #4712 actually showed it being confusing when it doesn't
work this way, we can make a simpler and more definitive statement
about this behavior. Additionally, language about "subtransactions"
is minimized as I might be removing or de-emphasizing this concept in
2.0 (though maybe not as it does seem to work well).
Mike Bayer [Tue, 28 May 2019 13:46:20 +0000 (09:46 -0400)]
Reformat license name
While we have the OSI classifier for "MIT License", it looks
like for the "license" field, this is normally just the word
"MIT" and not "MIT License". While the pypa docs suggest we
only need it as the OSI classifier, keep it also in "license"
in order to appease common tooling.
Mike Bayer [Fri, 5 Apr 2019 01:43:12 +0000 (21:43 -0400)]
Enhance documentation for string compilation use cases
- Add a web link for UnsupportedCompilationError
- Add new section to errors.rst
- add more detail and cross-linking to the FAQ
- include security caveats for parameter rendering
Mike Bayer [Fri, 8 Mar 2019 23:36:33 +0000 (18:36 -0500)]
Commit transaction after SNAPSHOT isolation change
A commit() is emitted after an isolation level change to SNAPSHOT, as both
pyodbc and pymssql open an implicit transaction which blocks subsequent SQL
from being emitted in the current transaction.
Mike Bayer [Fri, 8 Mar 2019 14:54:58 +0000 (09:54 -0500)]
Update the mysql-connector-python docs for now
mysql-connector-python still seems to have issues with binary datatypes
but the other issues here, with the possible exception of the deadlock
still being investigated, seem to have been resolved in the recent
8.x series of mysql-connector-python. The driver is still not
recommended due to these issues however we don't need a special
class of warnings at this point.
Fix large_resultsets performance example field name
Fixed bug in large_resultsets example case where a re-named "id" variable
due to code reformatting caused the test to fail. Pull request courtesy
Matt Schuchhardt.
Sanjana [Thu, 28 Feb 2019 15:16:13 +0000 (10:16 -0500)]
Add port comparison in __eq__() and __ne__() method to URL
Comparing two objects of :class:`.URL` using ``__eq__()`` did not take port
number into consideration, two objects differing only by port number were
considered equal. Port comparison is now added in ``__eq__()`` method of
:class:`.URL`, objects differing by port number are now not equal.
Additionally, ``__ne__()`` was not implemented for :class:`.URL` which
caused unexpected result when ``!=`` was used in Python2, since there are no
implied relationships among the comparison operators in Python2.
Mike Bayer [Wed, 20 Feb 2019 00:46:17 +0000 (19:46 -0500)]
Ensure _simple_lazy_clause bind names are fixed before cloning
Fixed a regression in 1.2 due to the introduction of baked queries for
relationship lazy loaders, where a race condition is created during the
generation of the "lazy clause" which occurs within a memoized attribute. If
two threads initialize the memoized attribute concurrently, the baked query
could be generated with bind parameter keys that are then replaced with new
keys by the next run, leading to a lazy load query that specifies the
related criteria as ``None``. The fix establishes that the parameter names
are fixed before the new clause and parameter objects are generated, so that
the names are the same every time.
Mike Bayer [Tue, 19 Feb 2019 17:13:04 +0000 (12:13 -0500)]
Add NCHAR to Oracle dialect
Added support for reflection of the :class:`.NCHAR` datatype to the Oracle
dialect, and added :class:`.NCHAR` to the list of types exported by the
Oracle dialect.
sanjana [Wed, 13 Feb 2019 15:17:46 +0000 (10:17 -0500)]
Adding setter to should_evaluate_none property
Fixed issue where the :class:`.JSON` type had a read-only
:attr:`.JSON.should_evaluate_none` attribute, which would cause failures
when making use of the :meth:`.TypeEngine.evaluates_none` method in
conjunction with this type. Pull request courtesy Sanjana S.
projects / thirdparty / sqlalchemy / sqlalchemy.git / log
