YOUR NAME HERE

Tutorials

How-to Guides

Explanation

Reference

+ +

Explanation¶

Asynchronous Programming 101
- The Story
- Cooperative multitasking
- Pros and cons
+
Engine and Connection
- Creating Engines
- Managing Connections
  - reuse
  - lazy
  - reusable
  - current_connection
  +
- Executing Queries
- Implicit Execution
+
Why Asynchronous ORM?
- When asyncio Helps
- How to Access Database
- Asynchronous ORM Done Right
  - Don’t Starve.
  - Be explicit.
  - Be productive.
  +
+

+ + +

+ + + +
+ This work is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License. +

+ +

Explanation

+ + +

+ +

+ Add your language here. +

+ +

+ +

+ + + + + + + + + + + \ No newline at end of file diff --git a/docs/en/1.0/explanation/async.html b/docs/en/1.0/explanation/async.html new file mode 100644 index 0000000..dbd597d --- /dev/null +++ b/docs/en/1.0/explanation/async.html @@ -0,0 +1,372 @@ + + + + + + + + Asynchronous Programming 101 - GINO 1.0.2.dev0 documentation + + + + + + + + + + + +

+ + +

Tutorials

How-to Guides

Explanation

Reference

+ +

Asynchronous Programming 101¶

The Story¶

Let’s say we want to build a search engine. We’ll use a single core computer to +build our index. To make things simpler, our tasks are to fetch web pages +(I/O operation), and process their content (CPU operation). Each task looks +like this:

We have lots of web pages to index, so we simply handle them one by one:

Let’s assume the time of each task is constant: each second, 2 tasks are done. +Thus we can say what the throughput of the current system is 2 tasks/sec. How +can we improve the throughput? An obvious answer is to add more CPU cores:

This simply doubles our throughput to 4 tasks/sec, and linearly scales as we +add more CPU cores, if the network is not a bottleneck. But can we improve +the throughput for each CPU core? The answer is yes, we can use +multi-threading:

Wait a second! The 2 threads barely finished 6 tasks in 2 seconds, a +throughput of only 2.7 tasks/sec, much lower than 4 tasks/sec with 2 cores. +What’s wrong with multi-threading? From the diagram we can see:

There are yellow bars taking up extra time.
The green bars can still overlap with any bar in the other thread, but
non-green bars cannot overlap with non-green bars in the other thread.

The yellow bars are time taken by context switches, a necessary part of allowing +multiple threads or processes to run on a single CPU core concurrently. +One CPU core can do only one thing at a time (let’s assume a world without +Hyper-threading or similar), +so in order to run several threads concurrently the CPU must split its +time into small +slices, and run a little bit of each thread within these slices. The yellow bar +is the overhead for the CPU to switch context to run a different thread. The +scale is a bit dramatic, but it helps with the point.

Wait again here, the green bars are overlapping between threads. Is the CPU +doing two things at the same time? No, the CPU is doing nothing in the middle +of the green bar, because it’s waiting for the HTTP response (I/O). That’s how +multi-threading could improve the throughput to 2.7 tasks/sec, instead of +decreasing it to 1.7 tasks/sec. You may try in real to run CPU-intensive +tasks with multi-threading on single core, there won’t be any improvement. Like +the multiplexed red bars (in practice there might be more context switches +depending on the task), they appear to be running at the same time, but the +total time for all to finish is actually longer than running the tasks one +by one. That’s also why this is called concurrency instead of parallelism.

As you might imagine, throughput will improve less with each additional thread, +until throughput begins to decrease because context switches are wasting too +much time, not to mention the extra memory footprint taken by new threads. It +is usually not practical to have tens of thousands of threads running on a single +CPU core. How, then, is it possible to have tens of thousands of I/O-bound tasks +running concurrently on a single CPU core? This is the once-famous C10k +problem, usually solved by +asynchronous I/O:

Note

Asynchronous I/O and coroutines are two different things, but they usually +go together. Here we will stick with coroutines for simplicity.

Awesome! The throughput is 3.7 tasks/sec, nearly as good as 4 tasks/sec of 2 +CPU cores. Though this is not real data, compared to OS threads coroutines +do take much less time to context switch and have a lower memory footprint, +thus making them an ideal option for the C10k problem.

Cooperative multitasking¶

So what is a coroutine?

In the last diagram above, you may have noticed a difference compared to the +previous diagrams: the green bars are overlapping within the same thread. +That is because the in the last diagram, our code is using asynchronous I/O, +whereas the previously we were using blocking I/O. As the name suggests, blocking +I/O will block the thread until the I/O result is ready. Thus, there can be only +one blocking I/O operation running in a thread at a time. To achieve concurrency +with blocking I/O, either multi-threading or multi-processing must be used. +In contrast, asynchronous I/O allows thousands (or even more) of concurrent +I/O reads and writes within the same thread, with each I/O operation blocking +only the coroutine performing the I/O rather than the whole thread. Like +multi-threading, coroutines provide a means to have concurrency during I/O, +but unlike multi-threading this concurrency occurs within a single thread.

Threads are scheduled by the operating system using an approach called preemptive +multitasking. For +example, in previous multi-threading diagram there was only one CPU core. When +Thread 2 tried to start processing the first web page content, Thread 1 hadn’t +finished processing its own. The OS brutally interrupted Thread 1 and shared +some resource (time) for Thread 2. But Thread 1 also needed CPU time to finish +its processing at the same time, so in turn after a while the OS had to pause +Thread 2 and resume Thread 1. Depending on the size of the task, such turns may +happen several times, so that every thread may have a fair chance to run. It is +something like this:

Thread 1: I wanna run!
+OS: Okay, here you go...
+Thread 2: I wanna run!
+OS: Urh, alright one sec ... Thread 1, hold on for a while!
+Thread 1: Well I'm not done yet, but you are the boss.
+OS: It won't be long. Thread 2 it's your turn now.
+Thread 2: Yay! (&%#$@..+*&#)
+Thread 1: Can I run now?
+OS: Just a moment please ... Thread 2, give it a break!
+Thread 2: Alright ... but I really need the CPU.
+OS: You'll have it later. Thread 1, hurry up!
+

+

In contrast, coroutines are scheduled by themselves cooperatively with the help +of an event manager. The event manager lives in the same thread as the +coroutines and unlike the OS scheduler that forces context switches on threads, +the event manager acts only when coroutines pause themselves. A thread knows +when it wants to run, but coroutines don’t - only the event manager knows which +coroutine should run. The event manager may only trigger the next coroutine to +run after the previous coroutine yields control to wait for an event (e.g. +wait for an HTTP response). This approach to achieve concurrency is called +cooperative multitasking. It’s like this:

Coroutine 1: Let me know when event A arrives. I'm done here before that.
+Event manager: Okay. What about you, coroutine 2?
+Coroutine 2: Um I've got nothing to do here before event B.
+Event manager: Cool, I'll be watching.
+Event manager: (after a while) Hey coroutine 1, event A is here!
+Coroutine 1: Awesome! Let me see ... looks good, but I need event C now.
+Event manager: Very well. Seems event B arrived just now, coroutine 2?
+Coroutine 2: Oh wonderful! Let me store it in a file ... There! I'm all done.
+Event manager: Sweet! Since there's no sign of event C yet, I'll sleep for a while.
+(silence)
+Event manager: Damn, event C timed out!
+Coroutine 1: Arrrrh gotta kill myself with an exception :S
+Event manager: Up to you :/
+

+

For coroutines, a task cannot be paused externally, the task can only pause +itself from within. When there are a lot of coroutines, concurrency depends on +each of them pausing from time to time to wait for events. If you wrote a +coroutine that never paused, it would allow no concurrency at all when running +because no other coroutine would have a chance to run. On the other hand, you +can feel safe in the code between pauses, because no other coroutine can +run at the same time to mess up shared states. That’s why in the last diagram, +the red bars are not interleaved like threads.

Tip

In Python and asyncio, async def declares coroutines, await yields +control to event loop (event manager).

Pros and cons¶

Asynchronous I/O may handle tens of thousands of concurrent I/O operations in +the same thread. This can save a lot of CPU time from context switching, and +memory from multi-threading. Therefore if you are dealing with lots of I/O-bound +tasks concurrently, asynchronous I/O can efficiently use limited CPU and memory to +deliver greater throughput.

With coroutines, you can naturally write sequential code that is cooperatively +scheduled. If your business logic is complex, coroutines could greatly improve +readability of asynchronous I/O code.

However for a single task, asynchronous I/O can actually impair throughput. For +example, for a simple recv() operation blocking I/O would just block until +returning the result, but for asynchronous I/O additional steps are required: +register for the read event, wait until event arrives, try to recv(), repeat +until a result returns, and finally feed the result to a callback. With coroutines, +the framework cost is even larger. Thanks to uvloop this cost has been minimized +in Python, but it is still additional overhead compared to raw blocking I/O.

Timing in Asynchronous I/O is also less predictable because of its cooperative +nature. For example, in a coroutine you may want to sleep for 1 second. However, +if another coroutine received control and ran for 2 seconds, by the time we get +back to the first coroutine 2 seconds have already passed. Therefore, sleep(1) +means to wait for at least 1 second. In practice, you should try your best to make +sure that all code between await finishes ASAP, being literally cooperative. +Still, there can be code outside your control, so it is important to keep this +unpredictibility of timing in mind.

Finally, asynchronous programming is complicated. Writing good asynchronous code +is easier said than done, and debugging it is more difficult than debugging +similar synchronous code. Especially when a whole team is working on the +same piece of asynchronous code, it can easily go wrong. Therefore, a general +suggestion is to use asynchronous I/O carefully for I/O-bound high concurrency +scenarios only. It’s not a drop-in that will provide a performance boost, but +more like a sharp blade for concurrency with two edges. And if you are dealing with +time-critical tasks, think again to be sure.

+ + +

+ + + +
+ This work is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License. +

+ +

Asynchronous Programming 101
- The Story
- Cooperative multitasking
- Pros and cons
+

+ + +

+ +

+ Add your language here. +

+ +

+ +

+ + + + + + + + + + + \ No newline at end of file diff --git a/docs/en/1.0/explanation/engine.html b/docs/en/1.0/explanation/engine.html new file mode 100644 index 0000000..e1449bc --- /dev/null +++ b/docs/en/1.0/explanation/engine.html @@ -0,0 +1,679 @@ + + + + + + + + Engine and Connection - GINO 1.0.2.dev0 documentation + + + + + + + + + + + +

+ + +

Tutorials

How-to Guides

Explanation

Reference

+ +

Engine and Connection¶

GinoEngine is the core of GINO. It acts like a pool of +connections but also does the work of assembling everyone together:

Under the hood, engine is associated with a specific dialect instance on +creation, e.g. asyncpg dialect. The dialect is actually a set of classes that +implements GINO dialect API, offering all the details about how to operate on +this specific database. In the diagram, gray color means internal, while green +means touchable by end users.

During creation, the engine will also ask the dialect to create a database +connection pool for it. The pool type is also a part of the dialect API, +because asynchronous database drivers usually have their own pool +implementation, thus their GINO dialects should hide such implementation +differences behind the unified diagram API for engine to use.

Note

In SQLAlchemy, database drivers are supposed to follow the DB-API standard, +which does not usually provide a pool implementation. Therefore, SQLAlchemy +has its own pool implementation, created directly in engine. This is where +this diagram doesn’t fit SQLAlchemy.

The pool creates raw connections, not the GinoConnection +green in the diagram. The connection in the diagram is a many-to-one wrapper of +the raw connection, because of the reuse and lazy features, we’ll get to that +part later. The connection is created by the engine, thus inherits the same +dialect, and is used for running queries.

On the outer side, SQLAlchemy queries can be executed directly on the engine or +connection. When on engine, it will try to acquire a reusable connection to +actually execute the connection, and release the connection after use.

Note

Another difference to SQLAlchemy here: GINO execution methods always return +final results, while in SQLAlchemy accessing the result may cause further +implicit database accesses. Therefore GINO engine immediately releases the +connection when the execution method on the engine returns, but SQLAlchemy +can only release the connection implicitly when the result data is found +exhausted.

By immediately releasing a connection, GINO may not release the related raw +connection when the raw connection was reused from another parent +connection. We’ll get to this later.

GINO also supports implicit execution +without having to specify an engine or connection explicitly. This is done by +binding the engine to the db instance, also known as the +MetaData or the Gino instance. +You may possibly bind a GinoConnection instance, but that +is greatly not recommended because it is very much untested.

At last, as the ORM / CRUD feature, models are just add-ons on top of +everything else to generate queries. The parent model class is connected to a +db instance on creation, therefore the models can do implicit execution too +if their db has a bind.

Then let’s get to some details.

Creating Engines¶

GINO reuses the strategy system SQLAlchemy provides to create engines. The name +of GINO’s strategy to create asynchronous GinoEngine is +just gino, but only available after gino is imported:

import gino, sqlalchemy
+
+async def main():
+    e = await sqlalchemy.create_engine('postgresql://...', strategy='gino')
+    # e is a GinoEngine
+

+

Tip

Please read this SQLAlchemy document +to learn about writing database URLs.

Also the GINO strategy replaces the default driver of dialect postgresql:// +from psycopg2 to asyncpg, so that you don’t have to replace the URL +as it may be shared between GINO and vanilla SQLAlchemy in parallel. +Alternatively, you can explicitly specify the driver to use by +postgresql+asyncpg://... or just asyncpg://....

GINO also offers a shortcut as gino.create_engine(), which only sets the +default strategy to gino and does nothing more. So here is an identical +example:

import gino
+
+async def main():
+    e = await gino.create_engine('postgresql://...')
+    # e is also a GinoEngine
+

+

As you may have noticed, when using the GINO strategy, +create_engine() returns a coroutine, which must be awaited +for result. Because it will create a database connection pool behind the scene, +and actually making a few initial connections by default.

For it is just SQLAlchemy create_engine(), the same rules of +parameters apply in GINO too. Well for now, GINO only supports a small amount +of all the parameters listed in SQLAlchemy document (we are working on it!):

For Dialect:

isolation_level
paramstyle

For Engine:

While these parameters are discarded by GINO:

module

In addition, keyword arguments for creating the underlying pool is accepted +here. In the case of asyncpg, they are from create_pool(). +For example, we can create an engine without initial connections:

e = await gino.create_engine('postgresql://...', min_size=0)
+

+

Similar to SQLAlchemy, GINO also provides shortcut to create engine while +setting it as a bind. In SQLAlchemy it is like this:

import sqlalchemy
+
+metadata = sqlalchemy.MetaData()
+metadata.bind = 'postgresql://...'
+
+# or in short
+
+metadata = sqlalchemy.MetaData('postgresql://...')
+

+

This implicitly calls create_engine() under the hood. However +in GINO, creating an engine requires await, it can no longer be hidden +behind a normal assignment statement. Therefore, GINO removed the assignment +magic in subclass Gino, reverted it to simple assignment:

import gino
+
+db = gino.Gino()
+
+async def main():
+    # db.bind = 'postgresql://...' doesn't work!! It sets a string on bind
+    engine = await gino.create_engine('postgresql://...')
+    db.bind = engine
+

+

And provided a shortcut to do so:

engine = await db.set_bind('postgresql://...')
+

+

And another simpler shortcut for one-time usage:

db = await gino.Gino('postgresql://...')
+

+

To unset a bind and close the engine:

engine, db.bind = db.bind, None
+await engine.close()
+

+

Or with a shortcut correspondingly:

await engine.pop_bind().close()
+

+

Furthermore, the two steps can be combined into one shortcut with asynchronous +context manager:

async with db.with_bind('postgresql://...') as engine:
+    # your code here
+

+

Managing Connections¶

With a GinoEngine at hand, you can acquire connections +from the pool now:

conn = await engine.acquire()
+

+

Don’t forget to release it after use:

await conn.release()
+

+

Yes this can be easily missing. The recommended way is to use the asynchronous +context manager:

async with engine.acquire() as conn:
+    # play with the connection
+

+

Here conn is a GinoConnection instance. As mentioned +previously, GinoConnection is mapped to an underlying raw +connection, as shown in following diagram:

Each column has at most one actual raw connection, and the number is the +sequence the connections are created in this example. It is designed this way +so that GINO could offer two features for connection management: reuse and +lazy. They are keyword arguments on acquire() +and by default switched off.

reuse¶

When acquiring a GinoConnection (2), GINO will borrow a +raw connection (1) from the underlying pool first, and assign it to this +GinoConnection (2). This is the default behavior of +acquire() with no arguments given. Even when +you are nesting two acquires, you still get two actual raw connection +borrowed:

async with engine.acquire() as conn1:
+    async with engine.acquire() as conn2:
+        # conn2 is a completely different connection than conn1
+

+

But sometimes conn2 may exist in a different method:

async def outer():
+    async with engine.acquire() as conn1:
+        await inner()
+
+async def inner():
+    async with engine.acquire() as conn2:
+        # ...
+

+

And we probably wish inner could reuse the same raw connection in +outer to save some resource, or borrow a new one if inner is +individually called without outer:

async def outer():
+    async with engine.acquire() as conn1:
+        await inner(conn1)
+
+async def inner(conn2=None):
+    if conn2 is None:
+        async with engine.acquire() as conn2:
+            # ...
+    else:
+        # the same ... again
+

+

This is exactly the scenario reuse could be useful. We can simply tell the +acquire() to reuse the most recent reusable +connection in current context by setting reuse=True, as presented in this +identical example:

async def outer():
+    async with engine.acquire() as conn1:
+        await inner(conn1)
+
+async def inner():
+    async with engine.acquire(reuse=True) as conn2:
+        # ...
+

+

Back to previous diagram, the blue GinoConnection +instances (3, 4, 6) are “reusing connections” acquired with reuse=True, +while the green ones (2, 5, 7) are not, thus they become “reusable +connections”. The green reusable connections are put in a stack in current +context, so that acquire(reuse=True) always reuses the most recent +connection at the top of the stack. For example, (3) and (4) reuse the only +available (2) at that moment, therefore (2, 3, 4) all map to the same raw +connection (1). Then after (5), (6) no longer reuses (2) because (5) is now the +new head of the stack.

Tip

By context, we are actually referring to the context concept in +contextvars the +new module in Python 3.7, and its partial backport aiocontextvars. Simply speaking, you may +treat a series of function calls in a chain as in the same context, even if +there is an await. It’s something like a thread local in asyncio.

GinoConnection (2) may be created through +acquire(reuse=True) too - because the stack is empty before (2), there is +nothing to reuse, so (2) upgraded itself to a reusable connection.

Releasing a reusing connection won’t cause the reused raw connection being +returned to the pool, only directly releasing the reused +GinoConnection can do so. Connections should be released +in the reversed order as they are acquired, but if the reused connection is +released before reusing connections by accident, then all the reusing +connections depending on it will turn closed because they are reusing the same +raw connection which is returned to the pool, any further execution will fail. +For example, if (3) is released first, then (2) and (4) are still functional. +But if (2) is released first, then (3) and (4) will be released implicitly and +are no longer usable any more.

lazy¶

As you may have found, GinoConnection (5) does not have +an underlying raw connection, even when it is reused by (6). This is because +both (5) and (6) set lazy=True on acquire.

A lazy connection will not borrow a raw connection on creation, it will only do +so when have to, e.g. when executing a query or starting a transaction. For +example, GinoConnection (7) is acquired lazily without a +raw connection, and (8) is only created when a query is executed on (7):

async with engine.acquire(lazy=True) as conn:  # (7)
+    await conn.scalar('select now()')          # (8)
+

+

On implementation level, lazy is extremely easy in +acquire(): if lazy=False then borrow a raw +connection, else do nothing. That’s it. Before executing a query or starting a +transaction, GinoConnection will always try to borrow a +raw connection if there is none present. This allows GINO to “transiently +release” a raw connection, while all GinoConnection +mapped to this raw connection are put in lazy mode (again). This is especially +useful before you need to run some networking tasks in a database-related +context - the networking task may take a long time to finish, we don’t want to +waste a connection resource checked out for nothing. For example:

async with engine.acquire(lazy=True) as conn:  # (7)
+    await conn.scalar('select now()')          # (8)
+    await conn.release(permanent=False)        # release (8)
+    await asyncio.sleep(10)                    # simulate long I/O work
+    await conn.scalar('select now()')          # re-acquire a new raw connection,
+                                               #   not necessarily the same (8)
+

+

When used together with reuse, at most one raw connection may be borrowed +for one reusing chain. For example, executing queries on both (5) and (6) will +result only one raw connection checked out, no matter which executes first. It +is also worth noting that, if we set lazy=False on (6), then the raw +connection will be immediately borrowed on acquire, and shared between both (5) +and (6). It’s been quite a while, let me post the same diagram again:

reusable¶

Usually, you don’t have to worry about the two options reuse and lazy, +using the default acquire() will always create +a concrete GinoConnection with a new raw connection with +it. It is only that they are by default reusable (the green ones). If you need +an absolutely isolated unique connection that has no risk being reused, you may +use reusable=False on acquire. As shown in the diagram, the unreusable +GinoConnection is an orphan away from any stack:

async with engine.acquire():                    # (2)
+    async with engine.acquire(reusable=False):  # the unreusable connection
+        async with engine.acquire(reuse=True):  # (3)
+

+

Unreusable connections can be lazy. But it is usually meaningless to specify +both reuse=True and reusable=False at the same time, because reusing +connections are always unusable - they are also not in the stack. You cannot +reuse a reusing connection, you only reuse a reusable connection in the stack. +Making a reusing connection unreusable doesn’t make its related reusable +connection unreusable. Hmm if this is getting more confusing, just don’t use +acquire(reuse=True, reusable=False) unless you know what it does.

current_connection¶

Except for all scenarios supported by above three options, there is still one +left out: we may want to acquire a reusing-only connection. There is no such +option to do so, but GINO could do the same thing through +current_connection which is always the reusable +GinoConnection at the top of current stack, or None +if current stack is empty.

Tip

The different between current_connection +and acquire(reuse=True) is, the +latter always produces a GinoConnection, while the +former may not.

Executing Queries¶

Once you have a GinoConnection instance, you can start +executing queries with it. There are 6 variants of the execute method: +all(), +first(), +one(), +one_or_none(), +scalar() and +status(). They are basically the same: +accepting the same parameters, calling the same underlying methods. The +difference is how they treat the results:

all() returns all results in a +list, which may be empty when the query has no result, empty but +still a list.
first() returns the first result directly, +or None if there is no result at all. There is usually some optimization +behind the scene to efficiently get only the first result, instead of loading +the full result set into memory.
one() returns exactly one result. If there +is no result at all or if there are multiple results, an exception is raised.
one_or_none() is similar to +one(), but it returns None if there is +no result instead or raising an exception.
scalar() is similar to +first(), it returns the first value of the +first result. Quite convenient to just retrieve a scalar value from database, +like NOW(), MAX(), COUNT() or whatever generates a single value. +None is also returned when there is no result, it is up to you how to +distinguish no result and the first value is NULL.
status() executes the query and discard all +the query results at all. Instead it returns the execution status line as it +is, usually a textual string. Note, there may be no optimization to only +return the status without loading the results, so make your query generate +nothing if you don’t want any result.

By “result”, I meant RowProxy of SQLAlchemy - an +immutable row instance with both tuple and dict interfaces. +Database values are translated twice before they are eventually stored in a +RowProxy: first by the database driver (dialect) +from network payload to Python objects (see Type Conversion of +how asyncpg does this), second by SQLAlchemy +result_processor() depending on the actual +type and dialect.

The arguments taken by these 4 methods are identical to the ones accepted by +SQLAlchemy execute() (click to read more), +usually a plain string of SQL directly or a SQLAlchemy query clause, followed +by query parameters. In the case when multiple dictionaries are given to +multiparams, all 4 methods will always return None discarding all +results. Likewise, the parameter values are processed twice too: first by +bind_processor() then the database driver.

GINO also supports SQLAlchemy +execution_options() provided either on +engine level, +connection level or on +queries. At +the moment we are working on being compatible with SQLAlchemy execution +options. In the mean while, GINO provides several new execution options, for +example enabling return_model and providing a model will make +all() and +first() return ORM model instance(s) instead +of RowProxy instance(s). See also +execution_options() for more information.

In addition, GINO has an iterate() method to +traverse the query results progressively, instead of loading all the results at +once. This method takes the same arguments as the other 4 execute methods do, +and follows the same rule of data handling. For now with asyncpg, this creates +a server-side cursor.

Implicit Execution¶

Acquire a GinoConnection and execute queries on it, that +is the most explicit way. You can also execute queries on a +GinoEngine instance. In this case, a connection will be +acquired with reuse=True for you implicitly, and released after returning:

await engine.scalar('select now()')
+

+

Equals to:

async with engine.acquire(reuse=True) as conn:
+    await conn.scalar('select now()')
+

+

This allows you to easily write connectionless code. For example:

async def get_now():
+    return await engine.scalar('select now()')
+
+async def main():
+    async with engine.acquire():
+        now = await get_now()
+        await engine.status('UPDATE ...')
+

+

In this example, main() will take only one raw connection. get_now() +can also work alone out of any acquire() context, thanks to reuse.

Furthermore, GINO provides the same query APIs on Gino +directly. They are simply delegates to corresponding API methods on the +bind. This allows even engine-less programming:

db = gino.Gino()
+
+async def get_now():
+    return await db.scalar('select now()')
+
+async def main():
+    async with db.with_bind('postgresql://...'):
+        now = await get_now()
+        await db.status('UPDATE ...')
+

+

Note

In this example we didn’t put the two queries in an acquire() block, so +they might be executed in two different connections.

At last, the SQLAlchemy implicit execution +on queries also work in GINO, under an extension named gino:

await users_table.select().gino.all()
+

+

By default, the extension GinoExecutor is injected on +Executable as a property of name gino +at the creation of Gino instance. Therefore, any +Executable object has the gino +property for implicit execution. Similarly, the execution methods calls the +corresponding ones on the bind of the db instance.

+ + +

+ + + +
+ This work is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License. +

+ +

Engine and Connection
- Creating Engines
- Managing Connections
  - reuse
  - lazy
  - reusable
  - current_connection
  +
- Executing Queries
- Implicit Execution
+

+ + +

+ +

+ Add your language here. +

+ +

+ +

+ + + + + + + + + + + \ No newline at end of file diff --git a/docs/en/1.0/explanation/why.html b/docs/en/1.0/explanation/why.html new file mode 100644 index 0000000..532f6ff --- /dev/null +++ b/docs/en/1.0/explanation/why.html @@ -0,0 +1,407 @@ + + + + + + + + Why Asynchronous ORM? - GINO 1.0.2.dev0 documentation + + + + + + + + + + + +

+ + +

Tutorials

How-to Guides

Explanation

Reference

+ +

Why Asynchronous ORM?¶

Conclusion first: in many cases, you don’t need to use an asynchronous ORM, or even +asyncio itself. But when you do, it’s very important to get it done correctly.

When asyncio Helps¶

As Mike Bayer - the author of SQLAlchemy - pointed out, even +Python itself can be slower than the database operation in a stereotypical +business-style CRUD-ish application, because the modern databases are so fast when the +query is simple, and this kind of application usually deploys the database in a super +reliable network. In this case, it doesn’t make sense to say “Hey I wanna use asyncio +because I love this asynchronous ORM”.

The problem asyncio solves is quite different: when you need to deal with a lot of +concurrent tasks, some of which may block on I/O for arbitrary time, asyncio could +largely leverage the scalability with cooperative multitasking. This is explained in +Asynchronous Programming 101. So the ultimate reason to use asyncio should be the application itself, +not the database.

For example, a chat server may need to talk to tens of thousands of clients at the same +time. The clients are idle for most of the time, because the user didn’t send a message +in seconds, which is thousands of times longer than the time needed by the server to +handle the message. Obviously the last thing you want is to have tens of thousands of OS +threads to wait for each of those clients to reply, as it’ll disproportionately consume +way too much hardware resource. In contrast, asyncio could easily handle this +concurrency with reasonably tiny overhead.

Another example is authentication using OpenID Connect Authorization Code Flow as a Client. If +the Token Endpoint of the Authorization Server responds fast, everything is fine. But +once it’s delayed for even just a few seconds due to unreliable Internet or overloaded +server or whatever reasons, the Client would face a concurrency challenge. According to +Liebig’s law, the +minimum throughput of the Client or the Server determines the overall performance. +Comparing to asyncio, it’s not wise to use threading model to build the Client and rely +on the Internet which may make the Client the shortest stave.

Arbitrary delays may happen in the database too. In PostgreSQL, you can LISTEN to +some asynchronous events that happens unpredictably. Some normal bulk queries may also +take a long time to run, and the database locks can occasionally block too, especially +the dead ones. But these are usually not considered as a high-concurrency scenario, +because the database will possibly hit its bottleneck before your server does, or there +are smarter ways to handle such situations than asyncio. Nevertheless, the database +could be the reason to use asyncio, depending on the actual case.

In closing, there are scenarios when asyncio could help with concurrency issues. Now +that we know we will write an asynchronous server, then the next question is:

How to Access Database¶

The first thing to balance here is ORM - how much convenience would you like to +sacrifice for execution performance. As we are talking about ORM, let’s assume we need +at least some level of abstraction over raw SQL, or else low-level tools like asyncpg +would be a neat choice. Don’t get me wrong - asyncpg is great and convenient to use, but +there won’t be such a question “why asynchronous ORM” if we’re not seeking an objective +layer over bare SQL. It’s totally reasonable and sometimes beneficial and fun to play +with SQL in asynchronous contexts, it’s just out of our scope here.

Because simple queries are executed so fast in the database, one obvious but wrong +approach is to just run the query in the main thread. It won’t work because it will 100% +cause a dead lock - not a typical database dead lock, but a hybrid one between the +connection pool and cooperative multitasking. For example, here’s a very simple server:

import asyncio
+from fastapi import FastAPI
+from sqlalchemy import create_engine
+from sqlalchemy.orm import sessionmaker
+
+app = FastAPI()
+e = create_engine("postgresql://localhost")
+Session = sessionmaker(bind=e)
+
+
+@app.get("/")
+async def read_root():
+    session = Session()
+    try:
+        now = session.execute("SELECT now()").scalar()
+        await asyncio.sleep(0.1)  # do some async work
+        return str(now)
+    finally:
+        session.close()
+

+

This follows advices found in When do I construct a Session, when do I commit it, and when do I close it? from SQLAlchemy - linking +the session scope to the request scope. It works fine within 10 concurrent requests, +but freezes miserably for any number beyond 10: all requests hang and the only way to +stop the server is kill -9.

What just happened is called a resource starvation. While the first 10 +requests were waiting for the async work (sleep(0.1)), the 11th request came in and +tried to acquire a new database connection from the pool. But the connection pool is +already exhausted (default max_overflow=10) by the first 10 requests, the 11th +request was then blocked by the acquisition. However, this acquisition is unfortunately +a blocking operation, therefore the main thread is blocked and the first 10 requests +lost their chance to finish the async work and return their connection back to the pool +to resume the 11th’s acquisition.

The root cause of such starvation is making asynchronous calls in a transaction +scope created implicitly by the default autocommit=False. So other than limiting +the number of concurrent requests down to 10, a more reasonable solution is to avoid +doing asynchronous calls in transaction scopes by explicitly ending them:

@app.get("/")
+async def read_root():
+    session = Session()
+    try:
+        now = session.execute("SELECT now()").scalar()
+        session.rollback()  # return the connection to avoid starvation
+        await asyncio.sleep(0.1)  # do some async work
+        return str(now)
+    finally:
+        session.close()
+

+

Because of the implicit nature of typical ORMs, it’s very hard to identify all such +transaction scopes and make sure there’s no await in them - you may have started +an implicit transaction by simply accessing a property like current_user.name. In +practice, it is an impossible mission to correctly mix blocking ORM code with +asynchronous programming in the same thread. So never do this.

What about thread pool?

The idea is to defer all blocking code into a thread pool, and run asynchronous +cooperative multitasking in the main thread. This is theoretically possible, but the +same implicit ORM issue keeps haunting us - how do you guarantee there is no blocking +calls in the main thread? Taking one step back, let’s assume we could do this cleanly. +What would the code look like? There must be a clear API as the logical separation +between the blocking and asynchronous code - the server executes major DB-free business +logic in the main thread with asynchronous programming, and calls blocking methods for +encapsulated database operations in a thread pool.

This reminds me of its opposite pattern, where the main server runs in blocking mode, +deferring I/O intensive operations into a task queue like Celery. Both approaches solve +the problem, the reason to choose one over the other is on the concentration of business +logic - you’d want to write the majority of your code in the main server, and defer only +sub-tasks or low priority operations into a thread pool or task queue. In reality, using +a task queue to e.g. send emails is a more reasonable approach. If you’re doing that in +the opposite way, you may want to reconsider the design.

In summary, other than using raw SQL, the existing typical ORMs could not serve +asynchronous programming well enough. We need true asynchronous ORMs.

Asynchronous ORM Done Right¶

I would describe a proper asynchronous ORM as follows:

Don’t Starve.¶

The very basic requirement for an asynchronous ORM is to avoid resource starvation, at +least avoid the part caused by the ORM design. The fix is actually pretty +straightforward - just make everything async.

In the example above, if the connection acquisition is asynchronous, it won’t block the +main thread any more (it’ll block it’s own coroutine instead). Therefore, the other +tasks would get a chance to finish the async work and return the connection back to the +pool, thus the starvation is avoided:

@app.get("/")
+async def read_root():
+    async with db.acquire() as conn:  # }
+        async with conn.begin():      # } These two won't block the main thread
+            now = await db.scalar("SELECT now()")
+            await asyncio.sleep(0.1)  # do some async work
+            return str(now)
+

+

Even though this code won’t cause any resource starvation, using await within +database transactions is still strongly discouraged, unless it is for the database query +or absolutely necessary. Because after yielding the execution, we have no idea when we +can resume the following execution. That leads to a hanging transaction or at least an +unused database connection for a moment. Doing so won’t kill the server immediately, but +it has a few disadvantages:

As the database connection pool is usually much smaller than the asynchronous server +concurrency, this kind of code caps the concurrency down to the DB pool level.
Taking a database connection from the pool for nothing is a waste of resource, +especially when the database pool is the shortest stave.
Database transactions should be kept short as much as possible. Because long-hanging +transactions may keep certain database locks, leading to performance issues or even +triggering a chain reaction of deadlocks.

Be explicit.¶

With that said, it is especially important to make everything explicit - all the +connection acquisition, transactions and executions. Anything that will block must be +marked with an await or async with, so that you’ll know for sure when a +statement is trying to make any database I/O. Fortunately there’s no other way in +asyncio to do this - following the pattern of Twisted, asyncio is already forcing +explicit await for any asynchronous operations.

Being explicit in other part of the ORM design is also useful for enhancing the quality +of users’ code. This has nothing to do with asynchronous, it’s not a golden standard or +something with a clear cut either. For example:

We could design the ORM model instances to be stateless, so that the users don’t have +to learn and worry about maintaining the state of the instances.
There shouldn’t be any “buffered operations” which users could “flush” with a single +statement once for all.
The user should just give direct one-off commands and the ORM executes them right away.
Also I think the convenience tooling should be well-balanced, the user doesn’t have to +guess or remember what an API means - for example, there’re more than one ways to load +a many-to-one relationship, I’d prefer to write the query by myself rather than trying +to remember what “join_without_n_plus_1()” means.

Be productive.¶

Explicitness and productivity are kind of like two sides of the same coin - more +explicitness means less productive, and more convenience means less explicit. As we are +already using Python, being able to code productively is especially important. For an +asynchronous ORM, is it possible to find a proper balance between the two?

I think some of the fundamental principals must be explicit, for example the stateless +model and asynchronous yieldings. Then we could add convenient tooling on top of this +foundation as much as it doesn’t harm the basic explicitness. The tooling could better +be simple wrappers, grammar sugars or shortcuts for lengthy code, with a proper and +intuitive naming. This is mostly the idea behind GINO’s design.

Additionally, being able to leverage an existing ecosystem is also an important part in +productivity. People could use what they’ve learned directly, port what they wrote to +the new platform with minimum effort. More importantly - reuse some of the tools from +the ecosystem without having to reinvent the wheel again.

+ + +

+ + + +
+ This work is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License. +

+ +

Why Asynchronous ORM?
- When asyncio Helps
- How to Access Database
- Asynchronous ORM Done Right
  - Don’t Starve.
  - Be explicit.
  - Be productive.
  +
+

+ + +

+ +

+ Add your language here. +

+ +

+ +

+ + + + + + + + + + + \ No newline at end of file diff --git a/docs/en/1.0/genindex.html b/docs/en/1.0/genindex.html new file mode 100644 index 0000000..270c3b2 --- /dev/null +++ b/docs/en/1.0/genindex.html @@ -0,0 +1 @@ +

genindex.html

\ No newline at end of file diff --git a/docs/en/1.0/how-to.html b/docs/en/1.0/how-to.html new file mode 100644 index 0000000..c05fc43 --- /dev/null +++ b/docs/en/1.0/how-to.html @@ -0,0 +1,274 @@ + + + + + + + + How-to Guides - GINO 1.0.2.dev0 documentation + + + + + + + + + + + +

+ +

+ + + + + +

+ + + +

+ + HOME + + + CREDITS + + +

Tutorials

How-to Guides

How-to Guides
- Use Alembic
- Contributing
- CRUD
- Frequently Asked Questions
- JSON Property
- Loaders and Relationship
- Connection Pool
- Schema Declaration
- Transaction
+
Use Alembic
Contributing
CRUD
Frequently Asked Questions
JSON Property
Loaders and Relationship
Connection Pool
Schema Declaration
Transaction

Explanation

Reference

+ +

How-to Guides¶

+ + +

+ + + +
+ This work is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License. +

+ +

How-to Guides

+ + +

+ +

+ Add your language here. +

+ +

+ +

+ + + + + + + + + + + \ No newline at end of file diff --git a/docs/en/1.0/how-to/alembic.html b/docs/en/1.0/how-to/alembic.html new file mode 100644 index 0000000..e591c6a --- /dev/null +++ b/docs/en/1.0/how-to/alembic.html @@ -0,0 +1,294 @@ + + + + + + + + Use Alembic - GINO 1.0.2.dev0 documentation + + + + + + + + + + + +

+ +

+ + + + + + + +

+ + + +

+ + HOME + + + CREDITS + + +

Tutorials

How-to Guides

Explanation

Reference

+ +

Use Alembic¶

Alembic is a lightweight database migration tool for usage with the SQLAlchemy Database +Toolkit for Python. It’s also possible to use with GINO.

To add migrations to project first of all, add alembic as dependency:

$ pip install --user alembic
+

+

When you need to set up alembic for your project.

Prepare sample project. We will have a structure:

alembic_sample/
+    my_app/
+        models.py
+

+

Inside models.py define simple DB Model with GINO:

from gino import Gino
+
+db = Gino()
+
+class User(db.Model):
+    __tablename__ = 'users'
+
+    id = db.Column(db.Integer(), primary_key=True)
+    nickname = db.Column(db.Unicode(), default='noname')
+

+

Set up Alembic¶

This will need to be done only once. Go to the main folder of your project +alembic_sample and run:

$ alembic init alembic
+

+

Alembic will create a bunch of files and folders in your project directory. One of them +will be alembic.ini. Open alembic.ini (you can find it in the main project +folder alembic_sample). Now change property sqlalchemy.url = with your DB +credentials. Like this:

sqlalchemy.url = postgres://{{username}}:{{password}}@{{address}}/{{db_name}}
+

+

Next go to folder alembic/ and open env.py file. Inside the env.py file you +need to import the db object. In our case db object is db from models +modules. This is a variable that links to your Gino() instance.

Inside alembic/env.py:

from main_app.models import db
+

+

And change target_metadata = to:

target_metadata = db
+

+

That’s it. We finished setting up Alembic for a project.

Note

All alembic commands must be run always from the folder that contains the +alembic.ini file.

Create first migration revision¶

Same commands you must run each time when you make some changes in DB Models and want to +apply these changes to your DB Schema.

$ alembic revision -m "first migration" --autogenerate --head head
+

+

If you have any problems relative to package imports similar to this example:

File "alembic/env.py", line 7, in <module>
+    from main_app.models import db
+ModuleNotFoundError: No module named 'main_app'
+

+

Either install your project locally with pip install -e ., poetry install or +python setup.py develop, or add you package to PYTHONPATH, like this:

$ export PYTHONPATH=$PYTHONPATH:/full_path/to/alembic_sample
+

+

After the successful run of alembic revision in folder alembic/versions you will +see a file with new migration.

Apply migration on DB¶

Now time to apply migration to DB. It will create tables based on you DB Models.

$ alembic upgrade head
+

+

Great. Now you apply your first migration. Congratulations!

Next time, when you will make any changes in DB models just do:

$ alembic revision -m "your migration description" --autogenerate --head head
+

+

And

alembic upgrade head
+

+

Full documentation about how to work with Alembic migrations, downgrades and other +things - you can find in official docs https://alembic.sqlalchemy.org

+ + +

+ + + +
+ This work is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License. +

+ +

Use Alembic
+

+ + +

+ +

+ Add your language here. +

+ +

+ +

+ + + + + + + + + + + \ No newline at end of file diff --git a/docs/en/1.0/how-to/contributing.html b/docs/en/1.0/how-to/contributing.html new file mode 100644 index 0000000..113630b --- /dev/null +++ b/docs/en/1.0/how-to/contributing.html @@ -0,0 +1,357 @@ + + + + + + + + Contributing - GINO 1.0.2.dev0 documentation + + + + + + + + + + + +

+ +

+ + + + + + + +

+ + + +

+ + HOME + + + CREDITS + + +

Tutorials

How-to Guides

Explanation

Reference

+ +

Contributing¶

Contributions are welcome, and they are greatly appreciated! Every +little bit helps, and credit will always be given.

You can contribute in many ways:

Types of Contributions¶

Report Bugs¶

Report bugs at https://github.com/python-gino/gino/issues.

If you are reporting a bug, please include:

Your operating system name and version.
Any details about your local setup that might be helpful in troubleshooting.
Detailed steps to reproduce the bug.

Fix Bugs¶

Look through the GitHub issues for bugs. Anything tagged with “bug” +and “help wanted” is open to whoever wants to implement it.

Implement Features¶

Look through the GitHub issues for features. Anything tagged with “enhancement” +and “help wanted” is open to whoever wants to implement it.

Write Documentation¶

GINO could always use more documentation, whether as part of the +official GINO docs, in docstrings, or even on the web in blog posts, +articles, and such.

Submit Feedback¶

The best way to send feedback is to file an issue at https://github.com/python-gino/gino/issues.

If you are proposing a feature:

Explain in detail how it would work.
Keep the scope as narrow as possible, to make it easier to implement.
Remember that this is a volunteer-driven project, and that contributions +are welcome :)

Get Started!¶

Ready to contribute? Here’s how to set up gino for local development.

Fork the gino repo on GitHub.

Clone your fork locally:

$ git clone git@github.com:your_name_here/gino.git
+

+

Create a branch for local development:

$ cd gino/
+$ git checkout -b name-of-your-bugfix-or-feature
+

+

Now you can make your changes locally.

Create virtual environment. Example for virtualenvwrapper:
+
```
$ mkvirtualenv gino
+
```
+
+
Activate the environment and install requirements:
+
```
$ pip install -r requirements_dev.txt
+
```
+
+
When you’re done making changes, check that your changes pass syntax checks:
+
```
$ flake8 gino tests
+
```
+
+

7. And tests (including other Python versions with tox). +For tests you you will need running database server (see “Tips” section below for configuration details):

$ pytest tests
+$ tox
+

+

For docs run:
+
```
$ make docs
+
```
+
+

It will build and open up docs in your browser.

Commit your changes and push your branch to GitHub:

$ git add .
+$ git commit -m "Your detailed description of your changes."
+$ git push origin name-of-your-bugfix-or-feature
+

+

Submit a pull request through the GitHub website.

Pull Request Guidelines¶

Before you submit a pull request, check that it meets these guidelines:

The pull request should include tests.
If the pull request adds functionality, the docs should be updated. Put +your new functionality into a function with a docstring, and add the +feature to the list in README.rst.
The pull request should work for Python 3.5, 3.6, 3.7 and 3.8. Check +https://github.com/python-gino/gino/actions?query=event%3Apull_request +and make sure that the tests pass for all supported Python versions.

Tips¶

To run a subset of tests:

$ py.test -svx tests.test_gino
+

+

By default the tests run against a default installed postgres database. If you +wish to run against a separate database for the tests you can do this by first +creating a new database and user using ‘psql’ or similar:

CREATE ROLE gino WITH LOGIN ENCRYPTED PASSWORD 'gino';
+CREATE DATABASE gino WITH OWNER = gino;
+

+

Then run the tests like so:

$ export DB_USER=gino DB_PASS=gino DB_NAME=gino
+$ py.test
+

+

Here is an example for db server in docker. Some tests require ssl so you will need to run postgres with ssl enabled. +Terminal 1 (server):

$ openssl req -new -text -passout pass:abcd -subj /CN=localhost -out server.req -keyout privkey.pem
+$ openssl rsa -in privkey.pem -passin pass:abcd -out server.key
+$ openssl req -x509 -in server.req -text -key server.key -out server.crt
+$ chmod 600 server.key
+$ docker run --name gino_db --rm -it -p 5433:5432 -v "$(pwd)/server.crt:/var/lib/postgresql/server.crt:ro" -v "$(pwd)/server.key:/var/lib/postgresql/server.key:ro" postgres:12-alpine -c ssl=on -c ssl_cert_file=/var/lib/postgresql/server.crt -c ssl_key_file=/var/lib/postgresql/server.key
+

+

Terminal 2 (client):

$ export DB_USER=gino DB_PASS=gino DB_NAME=gino DB_PORT=5433
+$ docker exec gino_db psql -U postgres -c "CREATE ROLE $DB_USER WITH LOGIN ENCRYPTED PASSWORD '$DB_PASS'"
+$ docker exec gino_db psql -U postgres -c "CREATE DATABASE $DB_NAME WITH OWNER = $DB_USER;"
+$ pytest tests/test_aiohttp.py
+

+

+ + +

+ + + +
+ This work is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License. +

+ +

Contributing
- Types of Contributions
  - Report Bugs
  - Fix Bugs
  - Implement Features
  - Write Documentation
  - Submit Feedback
  +
- Get Started!
- Pull Request Guidelines
- Tips
+

+ + +

+ +

+ Add your language here. +

+ +

+ +

+ + + + + + + + + + + \ No newline at end of file diff --git a/docs/en/1.0/how-to/crud.html b/docs/en/1.0/how-to/crud.html new file mode 100644 index 0000000..4be0f36 --- /dev/null +++ b/docs/en/1.0/how-to/crud.html @@ -0,0 +1,192 @@ + + + + + + + + CRUD - GINO 1.0.2.dev0 documentation + + + + + + + + + + + +

+ +

+ + + + + + + +

+ + + +

+ + HOME + + + CREDITS + + +

Tutorials

How-to Guides

Explanation

Reference

+ +

CRUD¶

THIS IS A WIP

+ + +

+ + + +
+ This work is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License. +

+ +

CRUD

+ + +

+ +

+ Add your language here. +

+ +

+ +

+ + + + + + + + + + + \ No newline at end of file diff --git a/docs/en/1.0/how-to/faq.html b/docs/en/1.0/how-to/faq.html new file mode 100644 index 0000000..e629dcf --- /dev/null +++ b/docs/en/1.0/how-to/faq.html @@ -0,0 +1,555 @@ + + + + + + + + Frequently Asked Questions - GINO 1.0.2.dev0 documentation + + + + + + + + + + + +

+ + +

Tutorials

How-to Guides

Explanation

Reference

+ +

Frequently Asked Questions¶

SQLAlchemy 1.4 supports asyncio, what will GINO be?¶

Starting from 1.4, SQLAlchemy will support asyncio. +This is a great news to the SQLAlchemy-based ORMs including GINO, because the users will +have one more option, and many GINO hacks can be eventually cleaned up. SQLAlchemy +achieved both sync and async API with the same code base by encapsulating the use of +greenlet. As an “async” user, you don’t +need to worry about its internals in most cases, it’s fine to just use its async APIs. +Both SQLAlchemy Core and ORM will be async-compatible, but some ORM features that +involve implicit database accesses are disallowed.

Given such news, GINO no longer has to maintain its own asyncpg dialect for SQLAlchemy +in future versions (yay!). Still, GINO will focus on the differences and keep a +compatible API. To list some of the different/future features:

Contextual Connections (see Engine and Connection)
SQLAlchemy Core-based CRUD models
The GINO Loader system
Async MySQL support
Typing support ^NEW
Trio support ^NEW
Execution performance ^NEW

As SQLAlchemy async support is considered in Alpha level, GINO will include SQLAlchemy +1.4 support in GINO 2.0.0-alpha.x releases, while the current GINO 1.0.x and 1.1.x will +remain on SQLAlchemy 1.3. GINO 1.x will receive bug fixes and security updates until +both SQLAlchemy async support and GINO 2.x are stabilized.

ORM or not ORM?¶

GINO does perform the Object-Relational Mapping work under the +Data Mapper Pattern, but +it is just not a traditional ORM. The Objects in GINO are completely stateless +from database - they are pure plain Python objects in memory. Changing their +attribute values does not make them “dirty” - or in a different way of thinking +they are always “dirty”. Any access to database must be explicitly executed. +Using GINO is more like making up SQL clauses with Models and Objects, +executing them to make changes in database, or loading data from database and +wrapping the results with Objects again. Objects are just row data containers, +you are still dealing with SQL which is represented by Models and SQLAlchemy +core grammars. Besides GINO can be used in a completely non-ORM way.

Can I use features of SQLAlchemy ORM?¶

SQLAlchemy has two parts:

SQLAlchemy Core
SQLAlchemy ORM

GINO is built on top of SQLAlchemy Core, so SQLAlchemy ORM won’t work in GINO.

How to join?¶

GINO invented none about making up queries, everything for that is inherited +from SQLAlchemy. Therefore you just need to know how to write join in +SQLAlchemy. +Especially, Ádám made some amazing upgrades in +GINO #113 to make join easier, so +that you can use model classes directly as if they are tables in joining:

results = await User.join(Book).select().gino.all()
+

+

How to connect to database through SSL?¶

It depends on the dialect and database driver. For asyncpg, keyword arguments +on asyncpg.connect() are directly +available on create_engine() or db.set_bind(). Therefore, enabling SSL is rather easy:

engine = await gino.create_engine(..., ssl=True)
+

+

What is aiocontextvars and what does it do?¶

It is a partial backport of the new built-in module contextvars introduced in Python +3.7. In Python 3.5 and 3.6, aiocontextvars patches loop.create_task() +to copy context from caller as a workaround to simulate the same behavior. This +is also under discussion in upstream backport project, please read more here: +https://github.com/MagicStack/contextvars/issues/2

If you are using Python 3.7, then aiocontextvars does nothing at all.

Note

This answer is for GINO 0.8 and later, please check earlier versions of +this documentation if you are using GINO 0.7.

How to define relationships?¶

GINO 1.0 or lower doesn’t provide relationship definition feature found in typical ORMs. +However, you could always manually define your tables, design your queries and load the +results explicitly in GINO. Please see Loaders and Relationship for more information.

How to define index with multiple columns?¶

class User(db.Model):
+    __tablename__ = 'users'
+
+    first_name = db.Column(db.Unicode())
+    last_name = db.Column(db.Unicode())
+
+    _name_idx = db.Index('index_on_name', 'first_name', 'last_name')
+

+

The _name_idx is not used.

Is there a django admin interface for GINO?¶

Not quite yet, please follow this discussion.

How to use multiple databases for different users on the fly?¶

GINO models are linked to a Gino instance, while +Gino has an optional property bind to hold a +GinoEngine instance. So when you are executing:

user = await User.get(request.user_id)
+

+

The bind is implicitly used to execute the query.

In order to use multiple databases, you would need multiple +GinoEngine instances. Here’s a full example using FastAPI with +lazy engine creation:

from asyncio import Future
+from contextvars import ContextVar
+
+from fastapi import FastAPI, Request
+from gino import create_engine
+from gino.ext.starlette import Gino
+
+engines = {}
+dbname = ContextVar("dbname")
+
+
+class ContextualGino(Gino):
+    @property
+    def bind(self):
+        e = engines.get(dbname.get(""))
+        if e and e.done():
+            return e.result()
+        else:
+            return self._bind
+
+    @bind.setter
+    def bind(self, val):
+        self._bind = val
+
+
+app = FastAPI()
+db = ContextualGino(app)
+
+
+@app.middleware("http")
+async def lazy_engines(request: Request, call_next):
+    name = request.query_params.get("db", "postgres")
+    fut = engines.get(name)
+    if fut is None:
+        fut = engines[name] = Future()
+        try:
+            engine = await create_engine("postgresql://localhost/" + name)
+        except Exception as e:
+            fut.set_exception(e)
+            del engines[name]
+            raise
+        else:
+            fut.set_result(engine)
+    await fut
+    dbname.set(name)
+    return await call_next(request)
+
+
+@app.get("/")
+async def get():
+    return dict(dbname=await db.scalar("SELECT current_database()"))
+

+

How to load complex query results?¶

The API doc of gino.loader explains the available loaders, and there’re a few +examples in Loaders and Relationship too.

Below is an example with a joined result to load both a GINO model and an integer at the +same time, using a TupleLoader with two sub-loaders - +ModelLoader and ColumnLoader:

import asyncio
+import random
+import string
+
+import gino
+from gino.loader import ColumnLoader
+
+db = gino.Gino()
+
+
+class User(db.Model):
+    __tablename__ = 'users'
+
+    id = db.Column(db.Integer(), primary_key=True)
+    name = db.Column(db.Unicode())
+
+
+class Visit(db.Model):
+    __tablename__ = 'visits'
+
+    id = db.Column(db.Integer(), primary_key=True)
+    time = db.Column(db.DateTime(), server_default='now()')
+    user_id = db.Column(db.ForeignKey('users.id'))
+
+
+async def main():
+    async with db.with_bind('postgresql://localhost/gino'):
+        await db.gino.create_all()
+
+        for i in range(random.randint(5, 10)):
+            u = await User.create(
+                name=''.join(random.choices(string.ascii_letters, k=10)))
+            for v in range(random.randint(10, 20)):
+                await Visit.create(user_id=u.id)
+
+        visits = db.func.count(Visit.id)
+        q = db.select([
+            User,
+            visits,
+        ]).select_from(
+            User.outerjoin(Visit)
+        ).group_by(
+            *User,
+        ).gino.load((User, ColumnLoader(visits)))
+        async with db.transaction():
+            async for user, visits in q.iterate():
+                print(user.name, visits)
+
+        await db.gino.drop_all()
+
+
+asyncio.run(main())
+

+

Be ware of the tuple in .gino.load((...)).

How to do bulk or batch insert / update?¶

For a simple example, take a model that has one field, “name.” In your application you +have a list of names you would like to add to the database:

new_names = ["Austin", "Ali", "Jeff", "Marissa"]
+

+

To quickly insert the names in one query, first construct a dict with the +{"model_key": "value"} format:

new_names_dict = [dict(name=new_name) for new_name in new_names]
+>> [{'name': 'Austin'}, {'name': 'Ali'}, {'name': 'Jeff'}, {'name': 'Marissa'}]
+

+

Finally, run an insert statement on the model:

await User.insert().gino.all(new_names_dict)
+

+

How to print the executed SQL?¶

GINO uses the same approach from SQLAlchemy: create_engine(..., echo=True). +(Or db.set_bind(..., echo=True)) Please see also here.

If you use any extension, you can also set that in config, by db_echo or DB_ECHO.

How to run `EXISTS` SQL?¶

await db.scalar(db.exists().where(User.email == email).select())
+

+

How to work with Alembic?¶

The fact that Gino is a MetaData is the +key to use Alembic. Just import and set target_metadata = db in Alembic env.py +will do. See Use Alembic for more details.

How to join the same table twice?¶

This is the same pattern as described in SQLAlchemy Adjacency List Relationships, where you +have a table with “a foreign key reference to itself”, or join the same table more than +once, “to represent hierarchical data in flat tables.” We’d need to use +alias(), for example:

class User(db.Model):
+    __tablename__ = "users"
+
+    id = db.Column(db.Integer, primary_key=True)
+    parent_id = db.Column(db.ForeignKey("users.id"))
+
+Parent = User.alias()
+query = User.outerjoin(Parent, User.parent_id == Parent.id).select()
+users = await query.gino.load(User.load(parent=Parent)).all()
+

+

How to execute raw SQL with parameters?¶

Wrap the SQL with text(), and use keyword arguments:

query = db.text('SELECT * FROM users WHERE id = :id_val')
+row = await db.first(query, id_val=1)
+

+

You may even load the rows into model instances:

query = query.execution_options(loader=User)
+user = await db.first(query, id_val=1)
+

+

Gino engine is not initialized?¶

GINO models are linked to a Gino instance, while +Gino has an optional property bind to hold a +GinoEngine instance. So when you are executing:

user = await User.get(request.user_id)
+

+

The bind is implicitly used to execute the query. If bind is not set before +this, you’ll see this error:

gino.exceptions.UninitializedError: Gino engine is not initialized.
+

+

You could use either:

Call set_bind() or with_bind() to set the +bind on the Gino instance.
Use one of the Web framework extensions to set the bind for you in usually the server +start-up hook.

Use explicit bind for each execution, for example:

engine = await create_engine("...")
+# ...
+user = await User.get(request.user_id, bind=engine)
+

+

How can I do SQL xxxx in GINO?¶

GINO uses SQLAlchemy Core queries, so +please check its documentation on how to build queries. The GINO models are simply +wrappers of SQLAlchemy Table instances, and the column +attributes on GINO model classes are just SQLAlchemy Column +instances, you can use them in building your SQLAlchemy Core queries.

Alternatively, you could always execute the raw SQL directly, see How to execute raw SQL with parameters? above.

+ + +

+ + + +
+ This work is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License. +

+ +

Frequently Asked Questions
+

+ + +

+ +

+ Add your language here. +

+ +

+ +

+ + + + + + + + + + + \ No newline at end of file diff --git a/docs/en/1.0/how-to/json-props.html b/docs/en/1.0/how-to/json-props.html new file mode 100644 index 0000000..9a7090f --- /dev/null +++ b/docs/en/1.0/how-to/json-props.html @@ -0,0 +1,373 @@ + + + + + + + + JSON Property - GINO 1.0.2.dev0 documentation + + + + + + + + + + + +

+ + +

Tutorials

How-to Guides

Explanation

Reference

+ +

JSON Property¶

GINO provides additional support to leverage native JSON type in the database as +flexible GINO model fields.

Quick Start¶

from gino import Gino
+from sqlalchemy.dialects.postgresql import JSONB
+
+db = Gino()
+
+class User(db.Model):
+    __tablename__ = "users"
+
+    id = db.Column(db.Integer, primary_key=True)
+    name = db.Column(db.String)
+    profile = db.Column(JSONB, nullable=False, server_default="{}")
+
+    age = db.IntegerProperty()
+    birthday = db.DateTimeProperty()
+

+

The age and birthday are JSON properties stored in the profile column. You +may use them the same way as a normal GINO model field:

u = await User.create(name="daisy", age=18)
+print(u.name, u.age)  # daisy 18
+

+

Note

profile is the default column name for all JSON properties in a model. If you +need a different column name for some JSON properties, you’ll need to specify +explicitly:

audit_profile = db.Column(JSON, nullable=False, server_default="{}")
+
+access_log = db.ArrayProperty(prop_name="audit_profile")
+abnormal_detected = db.BooleanProperty(prop_name="audit_profile")
+

+

Using JSON properties in queries is supported:

await User.query.where(User.age > 16).gino.all()
+

+

This is simply translated into a native JSON query like this:

SELECT users.id, users.name, users.profile
+FROM users
+WHERE CAST((users.profile ->> $1) AS INTEGER) > $2;  -- ('age', 16)
+

+

Datetime type is very much the same:

from datetime import datetime
+
+await User.query.where(User.birthday > datetime(1990, 1, 1)).gino.all()
+

+

And the generated SQL:

SELECT users.id, users.name, users.profile
+FROM users
+WHERE CAST((users.profile ->> $1) AS TIMESTAMP WITHOUT TIME ZONE) > $2
+-- ('birthday', datetime.datetime(1990, 1, 1, 0, 0))
+

+

Here’s a list of all the supported JSON properties:

+ ++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

JSON Property	Python type	JSON type	Database Type
`StringProperty`	`str`	`string`	`text`
`IntegerProperty`	`int`	`number`	`int`
`BooleanProperty`	`bool`	`boolean`	`boolean`
`DateTimeProperty`	`datetime`	`string`	`text`
`ObjectProperty`	`dict`	`object`	JSON
`ArrayProperty`	`list`	`array`	JSON

Hooks¶

JSON property provides 2 instance-level hooks to customize the data:

class User(db.Model):
+    __tablename__ = "users"
+
+    id = db.Column(db.Integer, primary_key=True)
+    profile = db.Column(JSONB, nullable=False, server_default="{}")
+
+    age = db.IntegerProperty()
+
+    @age.before_set
+    def age(self, val):
+        return val - 1
+
+    @age.after_get
+    def age(self, val):
+        return val + 1
+
+u = await User.create(name="daisy", age=18)
+print(u.name, u.profile, u.age)  # daisy {'age': 17} 18
+

+

And 1 class-level hook to customize the SQLAlchemy expression of the property:

class User(db.Model):
+    __tablename__ = "users"
+
+    id = db.Column(db.Integer, primary_key=True)
+    profile = db.Column(JSONB, nullable=False, server_default="{}")
+
+    height = db.JSONProperty()
+
+    @height.expression
+    def height(cls, exp):
+        return exp.cast(db.Float)  # CAST(profile -> 'height' AS FLOAT)
+

+

Create Index on JSON Properties¶

We’ll need to use declared_attr() to wait until the model class +is initialized. The rest is very much the same as defining a usual index:

class User(db.Model):
+    __tablename__ = "users"
+
+    id = db.Column(db.Integer, primary_key=True)
+    profile = db.Column(JSONB, nullable=False, server_default="{}")
+
+    age = db.IntegerProperty()
+
+    @db.declared_attr
+    def age_idx(cls):
+        return db.Index("age_idx", cls.age)
+

+

This will lead to the SQL below executed if you run db.gino.create_all():

CREATE INDEX age_idx ON users (CAST(profile ->> 'age' AS INTEGER));
+

+

Warning

Alembic doesn’t support auto-generating revisions for functional indexes yet. You’ll +need to manually edit the revision. Please follow this issue for updates.

+ + +

+ + + +
+ This work is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License. +

+ +

JSON Property
- Quick Start
- Hooks
- Create Index on JSON Properties
+

+ + +

+ +

+ Add your language here. +

+ +

+ +

+ + + + + + + + + + + \ No newline at end of file diff --git a/docs/en/1.0/how-to/loaders.html b/docs/en/1.0/how-to/loaders.html new file mode 100644 index 0000000..a76b93f --- /dev/null +++ b/docs/en/1.0/how-to/loaders.html @@ -0,0 +1,636 @@ + + + + + + + + Loaders and Relationship - GINO 1.0.2.dev0 documentation + + + + + + + + + + + +

+ + +

Tutorials

How-to Guides

Explanation

Reference

+ +

Loaders and Relationship¶

Loaders are used to load database row results into objects.

GINO doesn’t support automated relationship. We insist explicit code style in +asynchronous programming and that conflicts with some usual ORM relationship +patterns. Instead, GINO provides a rich loader system to assist you with manual +relationships through foreign keys or whatever magic. That means, you are +responsible for writing the queries, and GINO could assemble objects for you +from the database result with loaders you defined.

Model Loader¶

The Model Loader is the magic behind GINO CRUD to translate database rows into +model objects. Through CRUD, Model Loaders are assembled internally for you, +you can still use it directly. For example, an ordinary query that returns rows +may look like this:

query = db.select([User])
+rows = await query.gino.all()
+

+

In order to load rows into User objects, you can provide an execution +option loader with a new ModelLoader instance:

from gino.loader import ModelLoader
+
+query = db.select([User])
+query = query.execution_options(loader=ModelLoader(User))
+users = await query.gino.all()
+

+

The ModelLoader would then load each database row into a +User object. As this is frequently used, GINO made it a shortcut:

query = db.select([User])
+query = query.execution_options(loader=User.load())
+users = await query.gino.all()
+

+

And another shortcut:

query = db.select([User])
+query = query.execution_options(loader=User)
+users = await query.gino.all()
+

+

Tip

User as loader is transformed into ModelLoader(User) by +Loader.get(), explained later in “Loader +Expression”.

And again:

query = db.select([User])
+users = await query.gino.load(User).all()
+

+

This is identical to the normal CRUD query:

users = await User.query.gino.all()
+

+

Loader Expression¶

So Loaders are actually row post-processors, they define how the database rows +should be processed and returned. Other than ModelLoader, +there’re also other loaders that could turn the database rows into different +results like based on your definition. GINO provides the Loader Expression +feature for you to easily assemble complex loaders.

Here is an example using all loaders at once:

uid, user, sep, cols = await db.select([User]).gino.load(
+    (
+        User.id,
+        User,
+        '|',
+        lambda row, ctx: len(row),
+    )
+).first()
+

+

Let’s check this piece by piece. Overall, the argument of +load() is a tuple. This is interpreted into a +TupleLoader, with each item of the tuple interpreted as a +Loader Expression recursively. That means, it is possible to nest tuples. The +result of a TupleLoader is a tuple.

Column in Loader Expressions are interpreted as +ColumnLoader. It simply outputs the value of the given +column in the database row. It is your responsibility to select the column in +the query. Please note, ColumnLoader uses the given +column as index to look for the value, not the name of the column. This is a +SQLAlchemy feature to support selecting multiple columns with the same name +from different tables in the same query, especially for ORM. So if you are +using raw textual SQL and wishing to use ColumnLoader, +you’ll have to declare columns for the query:

now = db.Column('time', db.DateTime())
+result = await db.first(db.text(
+    'SELECT now() AT TIME ZONE \'UTC\''
+).columns(
+    now,
+).gino.load(
+    ('now:', now)
+).query)
+print(*result)  # now: 2018-04-08 08:23:02.431847
+

+

Let’s get back to previous example. The second item in the tuple is a GINO +model class. As we’ve presented previously, it is interpreted into a +ModelLoader. By default, it loads the values of all the +columns of the give model, and create a new model instance with the values.

Tip

For a complex loader expression, the same row is given to all loaders, so +it doesn’t matter User.id is already used before the model loader.

The last item in the tuple is a callable, it will be called for each row with +two arguments: the first argument is the row itself, while the second is a +contextual value provided by outer loader, we’ll get to that later. Similar to +map(), the return value of the call will be the loaded result.

At last, if none of the above types matches a Loader Expression, it will be +treated as is. Like the '|' separator, it will show up as the third item +in every result returned by the query.

Many-to-One Relationship¶

A classic many-to-one relationship is also known as referencing - the model on +the “many” end keeps a single reference to the model on the “one” end. Although +GINO does not enforce it, usually people use a foreign key for the reference:

class Parent(db.Model):
+    __tablename__ = 'parents'
+    id = db.Column(db.Integer, primary_key=True)
+
+class Child(db.Model):
+    __tablename__ = 'children'
+    id = db.Column(db.Integer, primary_key=True)
+    parent_id = db.Column(db.Integer, db.ForeignKey('parents.id'))
+

+

So every child has a single parent (or no parent at all), while one parent may +have multiple children. GINO provides an easy way to load children with their +parents:

async for child in Child.load(parent=Parent).gino.iterate():
+    print(f'Parent of {child.id} is {child.parent.id}')
+

+

As you may have noticed, Child.load is exactly the shortcut to create +ModelLoader in the very first example. With some +additional keyword arguments, Child.load(parent=Parent) is still a +ModelLoader for Child, the model loader is at the +same time a query builder. It is identical to do this:

async for child in Child.load(parent=Parent).query.gino.iterate():
+    print(f'Parent of {child.id} is {child.parent.id}')
+

+

The query dynamically generates a SQLAlchemy query +based on the knowledge of the loader, and set the loader as execution option at +the same time. The Loader simply forwarded unknown +attributes to its query, that’s why .query can +be omitted.

For ModelLoader, all keyword arguments are interpreted as +subloaders, their results will be set to the attributes of the result model +under the corresponding keys using setattr(). For example, Parent is +interpreted as ModelLoader(Parent) which loads Parent instances, and +Parent instances are set as the parent attribute of the outer Child +instance.

Warning

If multiple children references the same parent, then each child owns a +unique parent instance with identical values.

Tip

You don’t have to define parent attribute on Child. But if you do, +you gain the ability to customize how parent is stored or retrieved. For +example, let’s store the parent instance as _parent:

class Child(db.Model):
+    __tablename__ = 'children'
+    id = db.Column(db.Integer, primary_key=True)
+    parent_id = db.Column(db.Integer, db.ForeignKey('parents.id'))
+    _parent = None
+
+    @property
+    def parent(self):
+        return self._parent
+
+    @parent.setter
+    def parent(self, value):
+        self._parent = value
+

+

The query builder works recursively. For ModelLoader, it +uses LEFT OUTER JOIN to connect the FROM clauses, in order to achieve +many-to-one scenario. The ON clause is determined automatically by foreign +keys. You can also customize the ON clause in case there is no foreign key +(a promise is a promise):

loader = Child.load(parent=Parent.on(Child.parent_id == Parent.id))
+async for child in loader.query.gino.iterate():
+    print(f'Parent of {child.id} is {child.parent.id}')
+

+

And subloaders can be nested:

subloader = Child.load(parent=Parent.on(Child.parent_id == Parent.id))
+loader = Grandson.load(parent=subloader.on(Grandson.parent_id == Child.id))
+

+

By now, GINO supports only loading many-to-one joined query. To modify a +relationship, just modify the reference column values.

Self Referencing¶

Warning

Experimental feature.

Self referencing is usually used to create a tree-like structure. For example:

class Category(db.Model):
+    __tablename__ = 'categories'
+    id = db.Column(db.Integer, primary_key=True)
+    parent_id = db.Column(db.Integer, db.ForeignKey('categories.id'))
+

+

In order to load leaf categories with their parents, an alias is needed:

Parent = Category.alias()
+

+

Then the query would be something like this:

parents = db.select([Category.parent_id])
+query = Category.load(parent=Parent.on(
+    Category.parent_id == Parent.id
+)).where(
+    ~Category.id.in_(db.select([Category.alias().parent_id]))
+)
+async for c in query.gino.iterate():
+    print(f'Leaf: {c.id}, Parent: {c.parent.id}')
+

+

The generated SQL looks like this:

SELECT categories.id, categories.parent_id, categories_1.id, categories_1.parent_id
+  FROM categories LEFT OUTER JOIN categories AS categories_1
+    ON categories.parent_id = categories_1.id
+ WHERE categories.id NOT IN (
+           SELECT categories_2.parent_id
+             FROM categories AS categories_2
+       )
+

+

Other Relationships¶

GINO 0.7.4 introduced an experimental distinct feature to reduce a result set +with loaders, combining rows under specified conditions. This made it possible +to build one-to-many relationships. Using the same parent-child example above, +we could load distinct parents with all their children:

class Parent(db.Model):
+    __tablename__ = 'parents'
+    id = db.Column(db.Integer, primary_key=True)
+
+    def __init__(self, **kw):
+        super().__init__(**kw)
+        self._children = set()
+
+    @property
+    def children(self):
+        return self._children
+
+    @children.setter
+    def add_child(self, child):
+        self._children.add(child)
+
+
+class Child(db.Model):
+    __tablename__ = 'children'
+    id = db.Column(db.Integer, primary_key=True)
+    parent_id = db.Column(db.Integer, db.ForeignKey('parents.id'))
+
+
+query = Child.outerjoin(Parent).select()
+parents = await query.gino.load(
+    Parent.distinct(Parent.id).load(add_child=Child)).all()
+

+

Here the query is still child outer-joining parent, but the loader is loading +parent instances with distinct IDs only, while storing all their children +through the add_child setter property. In detail for each row, a parent +instance is firstly loaded if no parent instance with the same ID was loaded +previously, or the same parent instance will be reused. Then a child instance +is loaded from the same row, and fed to the possibly reused parent instance by +parent.add_child = new_child.

Distinct loaders can be nested to load hierarchical data, but it cannot be used +as a query builder to automatically generate queries.

GINO provides no additional support for one-to-one relationship - the user +should make sure that the query produces rows of distinct instance pairs, and +load them with regular GINO model loaders. When in doubt, the distinct feature +can be used on both sides, but you’ll have to manually deal with the conflict +if more than one related instances are found. For example, we could keep only +the last child for each parent:

class Parent(db.Model):
+    __tablename__ = 'parents'
+    id = db.Column(db.Integer, primary_key=True)
+
+    def __init__(self, **kw):
+        super().__init__(**kw)
+        self._child = None
+
+    @property
+    def child(self):
+        return self._child
+
+    @child.setter
+    def child(self, child):
+        self._child = child
+
+
+class Child(db.Model):
+    __tablename__ = 'children'
+    id = db.Column(db.Integer, primary_key=True)
+    parent_id = db.Column(db.Integer, db.ForeignKey('parents.id'))
+
+
+query = Child.outerjoin(Parent).select()
+parents = await query.gino.load(
+    Parent.distinct(Parent.id).load(child=Child.distinct(Child.id))).all()
+

+

Similarly, you can build many-to-many relationships in the same way:

class Parent(db.Model):
+    __tablename__ = 'parents'
+    id = db.Column(db.Integer, primary_key=True)
+
+    def __init__(self, **kw):
+        super().__init__(**kw)
+        self._children = set()
+
+    @property
+    def children(self):
+        return self._children
+
+    def add_child(self, child):
+        self._children.add(child)
+        child._parents.add(self)
+
+
+class Child(db.Model):
+    __tablename__ = 'children'
+    id = db.Column(db.Integer, primary_key=True)
+
+    def __init__(self, **kw):
+        super().__init__(**kw)
+        self._parents = set()
+
+    @property
+    def parents(self):
+        return self._parents
+
+
+class ParentXChild(db.Model):
+    __tablename__ = 'parents_x_children'
+
+    parent_id = db.Column(db.Integer, db.ForeignKey('parents.id'))
+    child_id = db.Column(db.Integer, db.ForeignKey('children.id'))
+
+
+query = Parent.outerjoin(ParentXChild).outerjoin(Child).select()
+parents = await query.gino.load(
+    Parent.distinct(Parent.id).load(add_child=Child.distinct(Child.id))).all()
+

+

Likewise, there is for now no way to modify the relationships automatically, +you’ll have to manually create, delete or modify ParentXChild instances.

Advanced Usage of Loaders¶

You could use combined loaders flexibly in complex queries - loading +relationships is just one special use case. For example, you could load the count of +visits at the same time of loading each user, by using a tuple loader with two +items - model loader for the user, and column loader for the count:

import asyncio
+import random
+import string
+
+import gino
+from gino.loader import ColumnLoader
+
+db = gino.Gino()
+
+
+class User(db.Model):
+    __tablename__ = 'users'
+
+    id = db.Column(db.Integer(), primary_key=True)
+    name = db.Column(db.Unicode())
+
+
+class Visit(db.Model):
+    __tablename__ = 'visits'
+
+    id = db.Column(db.Integer(), primary_key=True)
+    time = db.Column(db.DateTime(), server_default='now()')
+    user_id = db.Column(db.ForeignKey('users.id'))
+
+
+async def main():
+    async with db.with_bind('postgresql://localhost/gino'):
+        await db.gino.create_all()
+
+        for i in range(random.randint(5, 10)):
+            u = await User.create(
+                name=''.join(random.choices(string.ascii_letters, k=10)))
+            for v in range(random.randint(10, 20)):
+                await Visit.create(user_id=u.id)
+
+        visits = db.func.count(Visit.id)
+        q = db.select([
+            User,
+            visits,
+        ]).select_from(
+            User.outerjoin(Visit)
+        ).group_by(
+            *User,
+        ).gino.load((User, ColumnLoader(visits)))
+        async with db.transaction():
+            async for user, visits in q.iterate():
+                print(user.name, visits)
+
+        await db.gino.drop_all()
+
+
+asyncio.run(main())
+

+

Using alias to get ID-ascending pairs from the same table:

ua1 = User.alias()
+ua2 = User.alias()
+join_query = select([ua1, ua2]).where(ua1.id < ua2.id)
+loader = ua1.load('id'), ua2.load('id')
+result = await join_query.gino.load(loader).all()
+print(result)  # e.g. [(1, 2), (1, 3), (2, 3)]
+

+

Potentially there could be a lot of different use cases of loaders. We’ll add +more inspiration here in the future.

+ + +

+ + + +
+ This work is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License. +

+ +

Loaders and Relationship
+

+ + +

+ +

+ Add your language here. +

+ +

+ +

+ + + + + + + + + + + \ No newline at end of file diff --git a/docs/en/1.0/how-to/pool.html b/docs/en/1.0/how-to/pool.html new file mode 100644 index 0000000..e9a3021 --- /dev/null +++ b/docs/en/1.0/how-to/pool.html @@ -0,0 +1,214 @@ + + + + + + + + Connection Pool - GINO 1.0.2.dev0 documentation + + + + + + + + + + + +

+ + +

Tutorials

How-to Guides

Explanation

Reference

+ +

Connection Pool¶

Other than the default connection pool, alternative pools can be used in +their own use cases. +There are options from dialects (currently only +NullPool), and users can define their own pools. +The base class should be Pool.

To use non-default pools in raw GINO:

from gino.dialects.asyncpg import NullPool
+create_engine('postgresql://...', pool_class=NullPool)
+

+

To use non-default pools in extensions (taking Sanic as an example):

from gino.dialects.asyncpg import NullPool
+from gino.ext.sanic import Gino
+
+app = sanic.Sanic()
+app.config.DB_HOST = 'localhost'
+app.config.DB_KWARGS = dict(
+    pool_class=NullPool,
+)
+db = Gino()
+db.init_app(app)
+

+

+ + +

+ + + +
+ This work is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License. +

+ +

Connection Pool

+ + +

+ +

+ Add your language here. +

+ +

+ +

+ + + + + + + + + + + \ No newline at end of file diff --git a/docs/en/1.0/how-to/schema.html b/docs/en/1.0/how-to/schema.html new file mode 100644 index 0000000..b492d1f --- /dev/null +++ b/docs/en/1.0/how-to/schema.html @@ -0,0 +1,416 @@ + + + + + + + + Schema Declaration - GINO 1.0.2.dev0 documentation + + + + + + + + + + + +

+ + +

Tutorials

How-to Guides

Explanation

Reference

+ +

Schema Declaration¶

There are 3 ways to declare your database schema to be used with GINO. Because +GINO is built on top of SQLAlchemy core, either way you are actually declaring +SQLAlchemy Table.

GINO Engine¶

This is the minimized way to use GINO - using only +GinoEngine (and GinoConnection +too), everything else are vanilla SQLAlchemy core. This is useful when you have +legacy code written in SQLAlchemy core, in need of porting to asyncio. For new +code please use the other two.

For example, the table declaration is the same as SQLAlchemy core tutorial:

from sqlalchemy import Table, Column, Integer, String, MetaData, ForeignKey
+
+metadata = MetaData()
+
+users = Table(
+    'users', metadata,
+
+    Column('id', Integer, primary_key=True),
+    Column('name', String),
+    Column('fullname', String),
+)
+
+addresses = Table(
+    'addresses', metadata,
+
+    Column('id', Integer, primary_key=True),
+    Column('user_id', None, ForeignKey('users.id')),
+    Column('email_address', String, nullable=False)
+)
+

+

Note

When using GINO Engine only, it is usually your own business to create the +tables with either create_all() on a +normal non-async SQLAlchemy engine, or using Alembic. However it is still +possible to be done with GINO if it had to:

import gino
+from gino.schema import GinoSchemaVisitor
+
+async def main():
+    engine = await gino.create_engine('postgresql://...')
+    await GinoSchemaVisitor(metadata).create_all(engine)
+

+

Then, construct queries, in SQLAlchemy core too:

ins = users.insert().values(name='jack', fullname='Jack Jones')
+

+

So far, everything is still in SQLAlchemy. Now let’s get connected and execute +the insert:

async def main():
+    engine = await gino.create_engine('postgresql://localhost/gino')
+    conn = await engine.acquire()
+    await conn.status(ins)
+    print(await conn.all(users.select()))
+    # Outputs: [(1, 'jack', 'Jack Jones')]
+

+

Here create_engine() creates a GinoEngine, +then acquire() checks out a +GinoConnection, and +status() executes the insert and returns the +status text. This works similarly as SQLAlchemy +execute() - they take the same parameters +but return a bit differently. There are also other similar query APIs:

all() returns a list of +RowProxy
first() returns one +RowProxy, or None
one() returns one +RowProxy
one_or_none() returns one +RowProxy, or None
scalar() returns a single value, or +None
iterate() returns an asynchronous iterator +which yields RowProxy

Please go to their API for more information.

GINO Core¶

In previous scenario, GinoEngine must not be set to +metadata.bind because it is not a +regular SQLAlchemy Engine thus it won’t work correctly. For this, GINO provides +a subclass of MetaData as Gino, +usually instantiated globally under the name of db. It can be used as a +normal MetaData still offering some conveniences:

It delegates most public types you can access on sqlalchemy
It works with both normal SQLAlchemy engine and asynchronous GINO engine
It exposes all query APIs on GinoConnection level
It injects two gino extensions on SQLAlchemy query clauses and schema +items, allowing short inline execution like users.select().gino.all()
It is also the entry for the third scenario, see later

Then we can achieve previous scenario with less code like this:

from gino import Gino
+
+db = Gino()
+
+users = db.Table(
+    'users', db,
+
+    db.Column('id', db.Integer, primary_key=True),
+    db.Column('name', db.String),
+    db.Column('fullname', db.String),
+)
+
+addresses = db.Table(
+    'addresses', db,
+
+    db.Column('id', db.Integer, primary_key=True),
+    db.Column('user_id', None, db.ForeignKey('users.id')),
+    db.Column('email_address', db.String, nullable=False)
+)
+
+async def main():
+    async with db.with_bind('postgresql://localhost/gino'):
+        await db.gino.create_all()
+        await users.insert().values(
+            name='jack',
+            fullname='Jack Jones',
+        ).gino.status()
+        print(await users.select().gino.all())
+        # Outputs: [(1, 'jack', 'Jack Jones')]
+

+

Similar to SQLAlchemy core and ORM, this is GINO core. All tables and queries +are still made of SQLAlchemy whose rules still apply, but sqlalchemy seems +never imported. This is useful when ORM is unwanted.

Tip

asyncpgsa does the same thing, +but in a conceptually reversed way - instead of having asyncpg work for +SQLAlchemy, it made SQLAlchemy work for asyncpg (GINO used to be in that +way too because GINO is inspired by asyncpgsa). Either way works fine, it’s +just a matter of taste of whose API style to use, SQLAlchemy or asyncpg.

GINO ORM¶

If you want to further reduce the length of code, and taking a bit risk of +implicity, welcome to the ORM world. Even though GINO made itself not quite a +traditional ORM by being simple and explict to safely work with asyncio, common +ORM concepts are still valid - a table is a model class, a row is a model +instance. Still the same example rewritten in GINO ORM:

from gino import Gino
+
+db = Gino()
+
+
+class User(db.Model):
+    __tablename__ = 'users'
+
+    id = db.Column(db.Integer, primary_key=True)
+    name = db.Column(db.String)
+    fullname = db.Column(db.String)
+
+
+class Address(db.Model):
+    __tablename__ = 'addresses'
+
+    id = db.Column(db.Integer, primary_key=True)
+    user_id = db.Column(None, db.ForeignKey('users.id'))
+    email_address = db.Column(db.String, nullable=False)
+
+
+async def main():
+    async with db.with_bind('postgresql://localhost/gino'):
+        await db.gino.create_all()
+        await User.create(name='jack', fullname='Jack Jones')
+        print(await User.query.gino.all())
+        # Outputs: [<User object at 0x10a8ba860>]
+

+

Important

The __tablename__ is a mandatory field to define a concrete model.

As you can see, the declaration is pretty much the same as before. Underlying +they are identical, declaring two tables in db. The class style is just +more declarative. Instead of users.c.name, you can now access the column by +User.name. The implicitly created Table is +available at User.__table__ and Address.__table__. You can use anything +that works in GINO core here.

Note

Column names can be different as a class property and database column. +For example, name can be declared as +nickname = db.Column('name', db.Unicode(), default='noname'). In this +example, User.nickname is used to access the column, while in database, +the column name is name.

What’s worth mentioning is where raw SQL statements are used, or +TableClause is involved, like User.insert(), the original name is +required to be used, because in this case, GINO has no knowledge about the +mappings.

Tip

db.Model is a dynamically created parent class for your models. It is +associated with the db on initialization, therefore the table is put in +the very db when you declare your model class.

Things become different when it comes to CRUD. You can use model level methods +to directly create() a model instance, instead of +inserting a new row. Or delete() a model instance +without needing to specify the where clause manually. Query returns model +instances instead of RowProxy, and row values are +directly available as attributes on model instances. See also: +CRUD.

After all, GinoEngine is always in use. Next let’s dig +more into it.

+ + +

+ + + +
+ This work is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License. +

+ +

Schema Declaration
- GINO Engine
- GINO Core
- GINO ORM
+

+ + +

+ +

+ Add your language here. +

+ +

+ +

+ + + + + + + + + + + \ No newline at end of file diff --git a/docs/en/1.0/how-to/transaction.html b/docs/en/1.0/how-to/transaction.html new file mode 100644 index 0000000..02afeed --- /dev/null +++ b/docs/en/1.0/how-to/transaction.html @@ -0,0 +1,300 @@ + + + + + + + + Transaction - GINO 1.0.2.dev0 documentation + + + + + + + + + + + +

+ +

+ + + + + + + +

+ + + +

+ + HOME + + + CREDITS + + +

Tutorials

How-to Guides

Explanation

Reference

+ +

Transaction¶

It is crucial to correctly manage transactions in an asynchronous program, +because you never know how much time an await will actually wait for, it +will cause disasters if transactions are on hold for too long. GINO enforces +explicit transaction management to help dealing with it.

Basic usage¶

Transactions belong to GinoConnection. The most common +way to use transactions is through an async with statement:

async with connection.transaction() as tx:
+    await connection.status('INSERT INTO mytable VALUES(1, 2, 3)')
+

+

This guarantees a transaction is opened when entering the async with block, +and closed when exiting the block - committed if exits normally, or rolled back +by exception. The underlying transaction instance from the database driver is +available at raw_transaction, but in +most cases you don’t need to touch it.

GINO provides two convenient shortcuts to end the transaction early:

They will raise an internal exception to correspondingly commit or rollback the +transaction, thus the code within the async with block after +raise_commit() or +raise_rollback() is skipped. The +internal exception is inherited from BaseException so that normal try +... except Exception block can’t trap it. This exception stops propagating at +the end of async with block, so you don’t need to worry about handling it.

Transactions can also be started on a GinoEngine:

async with engine.transaction() as tx:
+    await engine.status('INSERT INTO mytable VALUES(1, 2, 3)')
+

+

Here a GinoConnection is borrowed implicitly before +entering the transaction, and guaranteed to be returned after transaction is +done. The GinoConnection instance is accessible at +tx.connection. Other than +that, everything else is the same.

Important

The implicit connection is by default borrowed with reuse=True. That +means using transaction() of +GinoEngine within a connection context is the same as +calling transaction() of the current +connection without having to reference it, no separate connection shall be +created.

Similarly, if your Gino instance has a bind, you may also do +the same on it:

async with db.transaction() as tx:
+    await db.status('INSERT INTO mytable VALUES(1, 2, 3)')
+

+

Nested Transactions¶

Transactions can be nested, nested transaction will create a savepoint as for +now on asyncpg. A similar example from asyncpg doc:

async with connection.transaction() as tx1:
+    await connection.status('CREATE TABLE mytab (a int)')
+
+    # Create a nested transaction:
+    async with connection.transaction() as tx2:
+        await connection.status('INSERT INTO mytab (a) VALUES (1), (2)')
+        # Rollback the nested transaction:
+        tx2.raise_rollback()
+
+    # Because the nested transaction was rolled back, there
+    # will be nothing in `mytab`.
+    assert await connection.all('SELECT a FROM mytab') == []
+

+

As you can see, the raise_rollback() +breaks only the async with block of the specified tx2, the outer +transaction tx1 just continued. What if we break the outer transaction from +within the inner transaction? The inner transaction context won’t trap the +internal exception because it recognizes the exception is not created upon +itself. Instead, the inner transaction context only follows the behavior to +either commit or rollback, and lets the exception propagate.

Because of the default reusing behavior, transactions on engine or db +follows the same nesting rules. Please see +GinoTransaction for more information.

Manual Control¶

Other than using async with, you can also manually control the +transaction:

tx = await connection.transaction()
+try:
+    await db.status('INSERT INTO mytable VALUES(1, 2, 3)')
+    await tx.commit()
+except Exception:
+    await tx.rollback()
+    raise
+

+

You can’t use raise_commit() or +raise_rollback() here, similarly it is +prohibited to use commit() and +rollback() in an async with block.

+ + +

+ + + +
+ This work is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License. +

+ +

Transaction
- Basic usage
- Nested Transactions
- Manual Control
+

+ + +

+ +

+ Add your language here. +

+ +

+ +

+ + + + + + + + + + + \ No newline at end of file diff --git a/docs/en/1.0/index.html b/docs/en/1.0/index.html new file mode 100644 index 0000000..701390f --- /dev/null +++ b/docs/en/1.0/index.html @@ -0,0 +1,228 @@ + + + + + + + + Welcome to GINO’s documentation! - GINO 1.0.2.dev0 documentation + + + + + + + + + + + +

+ +

+ + + +

+ + HOME + + + CREDITS + + +

Tutorials

How-to Guides

Explanation

Reference

+ +

Welcome to GINO’s documentation!¶

GINO - GINO Is Not ORM - is a lightweight asynchronous ORM built on top of +SQLAlchemy core for Python asyncio. Now (early 2020) GINO supports only one +dialect asyncpg.

Tutorials
+
Lessons for the newcomer to get started
+
How-to Guides
+
Solve specific problems by steps
+
Explanation
+
Explains the background and context
+
Reference
+
Describes the software as it is
+

Useful Links¶

Source Code
+
https://github.com/python-gino/gino
+
Community
+
https://gitter.im/python-gino/Lobby
+
BSD license
+
GINO is free software
+
Download
+
Download GINO from PyPI
+

Sections by Divio.

+ + +

+ + + +
+ This work is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License. +

+ +

+ Add your language here. +

+ +

+ +

+ + + + + + + + + + + \ No newline at end of file diff --git a/docs/en/1.0/objects.inv b/docs/en/1.0/objects.inv new file mode 100644 index 0000000..8938fe2 Binary files /dev/null and b/docs/en/1.0/objects.inv differ diff --git a/docs/en/1.0/py-modindex.html b/docs/en/1.0/py-modindex.html new file mode 100644 index 0000000..18dcbf9 --- /dev/null +++ b/docs/en/1.0/py-modindex.html @@ -0,0 +1 @@ +

domainindex.html

\ No newline at end of file diff --git a/docs/en/1.0/reference.html b/docs/en/1.0/reference.html new file mode 100644 index 0000000..c41ad01 --- /dev/null +++ b/docs/en/1.0/reference.html @@ -0,0 +1,327 @@ + + + + + + + + Reference - GINO 1.0.2.dev0 documentation + + + + + + + + + + + +

+ +

+ + + + + +

+ + + +

+ + HOME + + + CREDITS + + +

Tutorials

How-to Guides

Explanation

Reference

Reference
- API Reference
- Extensions
- History
+
API Reference
Extensions
History

+ +

Reference¶

API Reference
- gino package
  - Subpackages
    - gino.dialects package
      - Submodules
        +
        gino.dialects.asyncpg module
        +
        gino.dialects.base module
        +
        +
      - Module contents
      +
    - gino.ext package
      - Module contents
      +
    +
  - Submodules
    +
  - Module contents
  +
+
Extensions
- Sanic Support
  - Work with Sanic
  - Sanic Support
  +
- Starlette Support
  - Work with Starlette
  - Configuration
  - Lazy Connection
  +
- Tornado Support
+
History
- GINO 1.0
  +
- GINO 0.8
  - Migrating to GINO 0.8
    - 1. contextvars
    - 2. none_as_none
    +
  - 0.8.7 (2020-04-19)
  - 0.8.6 (2020-02-10)
  - 0.8.5 (2019-11-19)
  - 0.8.4 (2019-11-09)
  - 0.8.3 (2019-06-06)
  - 0.8.2 (2019-03-07)
  - 0.8.1 (2018-12-08)
  - 0.8.0 (2018-10-16)
  +
- GINO 0.7
  +
- GINO 0.6
  - Migrating to GINO 0.6
    - 1. Task Local
    - 2. Engine
    - 3. GinoConnection
    - 4. Query API
    - 5. Transaction
    +
  - 0.6.6 (2018-05-18)
  - 0.6.5 (2018-04-18)
  - 0.6.4 (2018-04-16)
  - 0.6.3 (2018-04-08)
  - 0.6.2 (2018-03-24)
  - 0.6.1 (2018-03-18)
  - 0.6.0 (2018-03-14)
  +
- GINO 0.5
  +
- Early Development Releases
  +
+

+ + +

+ + + +
+ This work is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License. +

+ +

Reference

+ + +

+ +

+ Add your language here. +

+ +

+ +

+ + + + + + + + + + + \ No newline at end of file diff --git a/docs/en/1.0/reference/api.html b/docs/en/1.0/reference/api.html new file mode 100644 index 0000000..381fe91 --- /dev/null +++ b/docs/en/1.0/reference/api.html @@ -0,0 +1,237 @@ + + + + + + + + API Reference - GINO 1.0.2.dev0 documentation + + + + + + + + + + + +

+ +

+ + + + + + + +

+ + + +

+ + HOME + + + CREDITS + + +

Tutorials

How-to Guides

Explanation

Reference

Reference
- API Reference
- Extensions
- History
+
API Reference
- gino package
+
Extensions
History

+ +

API Reference¶

+ +

+ + +

+ + + +
+ This work is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License. +

+ +

API Reference

+ + +

+ +

+ Add your language here. +

+ +

+ +

+ + + + + + + + + + + \ No newline at end of file diff --git a/docs/en/1.0/reference/api/gino.aiocontextvars.html b/docs/en/1.0/reference/api/gino.aiocontextvars.html new file mode 100644 index 0000000..70263b3 --- /dev/null +++ b/docs/en/1.0/reference/api/gino.aiocontextvars.html @@ -0,0 +1,213 @@ + + + + + + + + gino.aiocontextvars module - GINO 1.0.2.dev0 documentation + + + + + + + + + + + +

+ + +

Tutorials

How-to Guides

Explanation

Reference

Reference
- API Reference
- Extensions
- History
+
API Reference
- gino package
+
Extensions
History

+ +

gino.aiocontextvars module¶

+gino.aiocontextvars.patch_asyncio()¶

Patches asyncio to support contextvars.

This is automatically called when gino is imported. If Python version is 3.7 +or greater, this function is a no-op.

+ +

+ + +

+ + + +
+ This work is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License. +

+ +

gino.aiocontextvars module

+ + +

+ +

+ Add your language here. +

+ +

+ +

+ + + + + + + + + + + \ No newline at end of file diff --git a/docs/en/1.0/reference/api/gino.api.html b/docs/en/1.0/reference/api/gino.api.html new file mode 100644 index 0000000..b78c130 --- /dev/null +++ b/docs/en/1.0/reference/api/gino.api.html @@ -0,0 +1,584 @@ + + + + + + + + gino.api module - GINO 1.0.2.dev0 documentation + + + + + + + + + + + +

+ + +

Tutorials

How-to Guides

Explanation

Reference

Reference
- API Reference
- Extensions
- History
+
API Reference
- gino package
+
Extensions
History

+ +

gino.api module¶

+class gino.api.Gino(bind=None, model_classes=None, query_ext=True, schema_ext=True, ext=True, **kwargs)¶

Bases: sqlalchemy.sql.schema.MetaData

All-in-one API class of GINO, providing several shortcuts.

This class is a subclass of SQLAlchemy +MetaData, therefore its instances can be used +as a normal MetaData object, e.g. used in +Alembic. In usual cases, you would +want to define one global Gino instance, usually under the name +of db, representing the database used in your application.

You may define tables in the official way +SQLAlchemy core recommended, but more often in GINO we define model classes +with db.Model as their parent class to represent tables, for its +objective interface and CRUD operations. Please read CRUD +for more information.

For convenience, Gino instance delegated all properties publicly +exposed by sqlalchemy, so that you can define tables / models +without importing sqlalchemy:

id = db.Column(db.BigInteger(), primary_key=True)
+

+

Similar to MetaData, a Gino object +can bind to a GinoEngine instance, hereby allowing +“implicit execution” through the gino +extension on Executable or +SchemaItem constructs:

await User.query.gino.first()
+await db.gino.create_all()
+

+

Differently, GINO encourages the use of implicit execution and manages +transactional context correctly.

Binding to a connection object is not supported.

To set a bind property, you can simply set your +GinoEngine object on db.bind, or +set it to None to unbind. However, the creation of engine usually +happens at the same time. Therefore, GINO provided several convenient ways +doing so:

with_bind() returning an asynchronous context manager:

async with db.with_bind('postgresql://...') as engine:
+

+

set_bind() and pop_bind():

engine = await db.set_bind('postgresql://...')
+await db.pop_bind().close()
+

+

Directly await on Gino instance:

db = await gino.Gino('postgresql://...')
+await db.pop_bind().close()
+

+

Note

SQLAlchemy allows creating the engine by:

metadata.bind = 'postgresql://...'
+

+

While in GINO this only sets a string to bind, because +creating an engine requires await, which is exactly what +set_bind() does.

At last, Gino delegates all query APIs on the bound +GinoEngine.

+property Model¶: Declarative base class for models, subclass of +gino.declarative.Model. Defining subclasses of this class will +result new tables added to this Gino metadata.
+

+ +

+acquire(*args, **kwargs)¶: A delegate of GinoEngine.acquire().
+

+ +

+async all(clause, *multiparams, **params)¶: A delegate of GinoEngine.all().
+

+ +

+property bind¶

An GinoEngine to which this Gino is bound.

This is a simple property with no getter or setter hook - what you set +is what you get. To achieve the same result as it is in SQLAlchemy - +setting a string or URL and getting an +engine instance, use set_bind() (or await on this +Gino object after setting a string or +URL).

+ +

+compile(elem, *multiparams, **params)¶: A delegate of GinoEngine.compile().
+

+ +

+async first(clause, *multiparams, **params)¶: A delegate of GinoEngine.first().
+

+ +

+iterate(clause, *multiparams, **params)¶: A delegate of GinoEngine.iterate().
+

+ +

+model_base_classes = (<class 'gino.crud.CRUDModel'>,)¶

Overridable default model classes to build the Model.

Default is (CRUDModel, ).

+ +

+no_delegate = {'create_engine', 'engine_from_config'}¶: A set of symbols from sqlalchemy which is not delegated by +Gino.
+

+ +

+async one(clause, *multiparams, **params)¶: A delegate of GinoEngine.one().
+

+ +

+async one_or_none(clause, *multiparams, **params)¶: A delegate of GinoEngine.one_or_none().
+

+ +

+pop_bind()¶

Unbind self, and return the bound engine.

This is usually used in a chained call to close the engine:

await db.pop_bind().close()
+

+

Returns: GinoEngine or None if self is not bound.
+

+ +

+query_executor¶

The overridable gino extension class on +Executable.

This class will be set as the getter method of the property gino on +Executable and its subclasses, if +ext and query_ext arguments are both True. Default is +GinoExecutor.

alias of GinoExecutor

+ +

+async scalar(clause, *multiparams, **params)¶: A delegate of GinoEngine.scalar().
+

+ +

+schema_visitor¶: alias of gino.schema.GinoSchemaVisitor
+

+ +

+async set_bind(bind, loop=None, **kwargs)¶

Bind self to the given GinoEngine and return it.

If the given bind is a string or +URL, all arguments will be sent to +create_engine() to create a new engine, and return it.

Returns: GinoEngine
+

+ +

+async status(clause, *multiparams, **params)¶: A delegate of GinoEngine.status().
+

+ +

+transaction(*args, **kwargs)¶: A delegate of GinoEngine.transaction().
+

+ +

+with_bind(bind, loop=None, **kwargs)¶

Shortcut for set_bind() and pop_bind() plus closing engine.

This method accepts the same arguments of +create_engine(). This allows inline creating an engine and +binding self on enter, and unbinding self and closing the engine on +exit:

async with db.with_bind('postgresql://...') as engine:
+    # play with engine
+

+

Returns: An asynchronous context manager.
+

+ +

+class gino.api.GinoExecutor(query)¶

Bases: object

The default gino extension on +Executable constructs for implicit +execution.

Instances of this class are created when visiting the gino property of +Executable instances (also referred as +queries or clause elements), for example:

await User.query.gino.first()
+

+

This allows GINO to add the asynchronous query APIs (all(), +first(), one(), one_or_none(), scalar(), +status(), iterate()) to SQLAlchemy query clauses without +messing up with existing synchronous ones. +Calling these asynchronous query APIs has the same restriction - the +relevant metadata (the Gino instance) must be bound to an engine, +or an AttributeError will be raised.

Note

Executable clause elements that are completely irrelevant with any +table - for example db.select([db.text('now()')]) - has no +metadata, hence no engine. Therefore, this will always fail:

await db.select([db.text('now()')]).gino.scalar()
+

+

You should use conn.scalar(), +engine.scalar() or even +db.scalar() in this case.

+async all(*multiparams, **params)¶: Returns engine.all() with this query +as the first argument, and other arguments followed, where engine +is the GinoEngine to which the metadata +(Gino) is bound, while metadata is found in this query.
+

+ +

+async first(*multiparams, **params)¶: Returns engine.first() with this +query as the first argument, and other arguments followed, where +engine is the GinoEngine to which the metadata +(Gino) is bound, while metadata is found in this query.
+

+ +

+iterate(*multiparams, **params)¶: Returns engine.iterate() with this +query as the first argument, and other arguments followed, where +engine is the GinoEngine to which the metadata +(Gino) is bound, while metadata is found in this query.
+

+ +

+load(value)¶

Shortcut to set execution option loader in a chaining call.

For example to load Book instances with their authors:

query = Book.join(User).select()
+books = await query.gino.load(Book.load(author=User)).all()
+

+

Read execution_options() for more +information.

+ +

+model(model)¶

Shortcut to set execution option model in a chaining call.

Read execution_options() for more +information.

+ +

+async one(*multiparams, **params)¶: Returns engine.one() with this query +as the first argument, and other arguments followed, where engine +is the GinoEngine to which the metadata +(Gino) is bound, while metadata is found in this query.
+

+ +

+async one_or_none(*multiparams, **params)¶: Returns engine.one_or_none() +with this query as the first argument, and other arguments followed, +where engine is the GinoEngine to which the +metadata (Gino) is bound, while metadata is found in this +query.
+

+ +

+property query¶

Get back the chained Executable.

In a chained query calls, occasionally the previous query clause is +needed after a .gino. chain, you can use .query. to resume the +chain back. For example:

await User.query.gino.model(FOUser).query.where(...).gino.all()
+

+

+ +

+return_model(switch)¶

Shortcut to set execution option return_model in a chaining call.

Read execution_options() for more +information.

+ +

+async scalar(*multiparams, **params)¶: Returns engine.scalar() with this +query as the first argument, and other arguments followed, where +engine is the GinoEngine to which the metadata +(Gino) is bound, while metadata is found in this query.
+

+ +

+async status(*multiparams, **params)¶: Returns engine.status() with this +query as the first argument, and other arguments followed, where +engine is the GinoEngine to which the metadata +(Gino) is bound, while metadata is found in this query.
+

+ +

+timeout(timeout)¶

Shortcut to set execution option timeout in a chaining call.

Read execution_options() for more +information.

+ +

+ + +

+ + + +
+ This work is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License. +

+ +

gino.api module

+ + +

+ +

+ Add your language here. +

+ +

+ +

+ + + + + + + + + + + \ No newline at end of file diff --git a/docs/en/1.0/reference/api/gino.crud.html b/docs/en/1.0/reference/api/gino.crud.html new file mode 100644 index 0000000..0462674 --- /dev/null +++ b/docs/en/1.0/reference/api/gino.crud.html @@ -0,0 +1,650 @@ + + + + + + + + gino.crud module - GINO 1.0.2.dev0 documentation + + + + + + + + + + + +

+ + +

Tutorials

How-to Guides

Explanation

Reference

Reference
- API Reference
- Extensions
- History
+
API Reference
- gino package
+
Extensions
History

+ +

gino.crud module¶

+class gino.crud.Alias(model, *args, **kwargs)¶

Bases: object

Experimental proxy for table alias on model.

+distinct(*columns)¶

+ +

+load(*column_names, **relationships)¶

+ +

+on(on_clause)¶

+ +

+class gino.crud.CRUDModel(**values)¶

Bases: gino.declarative.Model

The base class for models with CRUD support.

Don’t inherit from this class directly, because it has no metadata. Use +db.Model instead.

+classmethod alias(*args, **kwargs)¶: Experimental proxy for table alias on model.
+

+ +

+append_where_primary_key(q)¶

Append where clause to locate this model instance by primary on the +given query, and return the new query.

This is mostly used internally in GINO, but also available for such +usage:

await user.append_where_primary_key(User.query).gino.first()
+

+

which is identical to:

await user.query.gino.first()
+

+

Deprecated since version 0.7.6: Use lookup() instead.

+ +

+create(bind=None, timeout=<object object>, **values)¶

This create behaves a bit different on model classes compared to model +instances.

On model classes, create will create a new model instance and insert +it into database. On model instances, create will just insert the +instance into the database.

Under the hood create() uses INSERT ... RETURNING ... to +create the new model instance and load it with database default data if +not specified.

Some examples:

user1 = await User.create(name='fantix', age=32)
+user2 = User(name='gino', age=42)
+await user2.create()
+

+

Parameters

bind – A GinoEngine to execute the +INSERT statement with, or None (default) to use the bound +engine on the metadata (Gino).
timeout – Seconds to wait for the database to finish executing, +None for wait forever. By default it will use the timeout +execution option value if unspecified.
values – Keyword arguments are pairs of attribute names and their +initial values. Only available when called on a model class.

Returns

The instance of this model class (newly created or existing).

+ +

+delete¶

Similar to update(), this delete is also different on model +classes than on model instances.

On model classes delete is an attribute of type +Delete for massive deletes, for +example:

await User.delete.where(User.enabled.is_(False)).gino.status()
+

+

Similarly you can add a returning() +clause to the query and it shall return the deleted rows as model objects.

And on model instances, delete() is a method to remove the +corresponding row in the database of this model instance. and returns the +status returned from the database:

print(await user.delete())  # e.g. prints DELETE 1
+

+

Note

delete() only removes the row from database, it does not affect the +current model instance.

Parameters

bind – An optional GinoEngine if current +metadata (Gino) has no bound engine, or specifying a +different GinoEngine to execute the DELETE.
timeout – Seconds to wait for the database to finish executing, +None for wait forever. By default it will use the timeout +execution option value if unspecified.

+ +

+classmethod distinct(*columns)¶: Experimental loader feature to yield only distinct instances by given +columns.
+

+ +

+async classmethod get(ident, bind=None, timeout=<object object>)¶

Get an instance of this model class by primary key.

For example:

user = await User.get(request.args.get('user_id'))
+

+

Parameters

ident – Value of the primary key. For composite primary keys this +should be a tuple of values for all keys in database order, or a dict +of names (or position numbers in database order starting from zero) +of all primary keys to their values.
bind – A GinoEngine to execute the +INSERT statement with, or None (default) to use the bound +engine on the metadata (Gino).
timeout – Seconds to wait for the database to finish executing, +None for wait forever. By default it will use the timeout +execution option value if unspecified.

Returns

An instance of this model class, or None if no such row.

+ +

+classmethod in_query(query)¶

Convenient method to get a Model object when using subqueries.

Though with filters and aggregations, subqueries often return same +columns as the original table, but SQLAlchemy could not recognize them +as the columns are in subqueries, so technically they’re columns in the +new “table”.

With this method, the columns are loaded into the original models when +being used in subqueries. For example:

query = query.alias('users')
+MyUser = User.in_query(query)
+
+loader = MyUser.distinct(User1.id).load()
+users = await query.gino.load(loader).all()
+

+

+ +

+classmethod load(*column_names, **relationships)¶

Populates a loader.Loader instance to be used by the +loader execution option in order to customize the loading behavior +to load specified fields into instances of this model.

The basic usage of this method is to provide the loader execution +option (if you are looking for reloading +the instance from database, check get() or query) for a +given query.

This method takes both positional arguments and keyword arguments with +very different meanings. The positional arguments should be column +names as strings, specifying only these columns should be loaded into +the model instance (other values are discarded even if they are +retrieved from database). Meanwhile, the keyword arguments should be +loaders for instance attributes. For example:

u = await User.query.gino.load(User.load('id', 'name')).first()
+

+

Tip

gino.load is a shortcut for setting the execution option +loader.

This will populate a User instance with only id and name +values, all the rest are simply None even if the query actually +returned all the column values.

q = User.join(Team).select()
+u = await q.gino.load(User.load(team=Team)).first()
+

+

This will load two instances of model User and Team, returning +the User instance with u.team set to the Team instance.

Both positional and keyword arguments can be used ath the same time. If +they are both omitted, like Team.load(), it is equivalent to just +Team as a loader.

Additionally, a loader.Loader instance can also be used to +generate queries, as its structure is usually the same as the query:

u = await User.load(team=Team).query.gino.first()
+

+

This generates a query like this:

SELECT users.xxx, ..., teams.xxx, ...
+  FROM users LEFT JOIN teams
+    ON ...
+

+

The Loader delegates attributes on the query, so +.query can be omitted. The LEFT JOIN is built-in behavior, +while the ON clause is generated based on foreign key. If there is +no foreign key, or the condition should be customized, you can use +this:

u = await User.load(
+    team=Team.on(User.team_id == Team.id)).gino.first()
+

+

And you can use both load() and on() at the same time +in a chain, in whatever order suits you.

See also

+ +

+lookup()¶

Generate where-clause expression to locate this model instance.

By default this method uses current values of all primary keys, and you +can override it to behave differently. Most instance-level CRUD +operations depend on this method internally. Particularly while +lookup() is called in update(), the where condition is +used in UpdateRequest.apply(), so that queries like UPDATE ... +SET id = NEW WHERE id = OLD could work correctly.

Returns: +

New in version 0.7.6.

+ +

+classmethod none_as_none(enabled=True)¶

+ +

+classmethod on(on_clause)¶: Customize the on-clause for the auto-generated outer join query.
+
+
Note
+
This has no effect when provided as the loader execution option +for a given query.
+
+
+
See also
+
load()
+
+

+ +

+query¶: Get a SQLAlchemy query clause of the table behind this model. This equals +to sqlalchemy.select([self.__table__]). If this attribute is retrieved on a +model instance, then a where clause to locate this instance by its primary +key is appended to the returning query clause. This model type is set as +the execution option model in the returning clause, so by default the +query yields instances of this model instead of database rows.
+

+ +

+select()¶

Build a query to retrieve only specified columns from this table.

This method accepts positional string arguments as names of attributes to +retrieve, and returns a Select for +query. The returning query object is always set with two execution options:

model is set to this model type
return_model is set to False

So that by default it always return rows instead of model instances, while +column types can be inferred correctly by the model option.

For example:

async for row in User.select('id', 'name').gino.iterate():
+    print(row['id'], row['name'])
+

+

If select() is invoked on a model instance, then a WHERE clause +to locate this instance by its primary key is appended to the returning +query clause. This is useful when you want to retrieve a latest value of a +field on current model instance from database:

db_age = await user.select('age').gino.scalar()
+

+

See also

+ +

+to_dict()¶

Convenient method to generate a dict from this model instance.

Keys will be attribute names, while values are loaded from memory (not +from database). If there are JSONProperty +attributes in this model, their source JSON field will not be included +in the returning dict - instead the JSON attributes will be.

See also

json_support

+ +

+update¶

This update behaves quite different on model classes rather than model +instances.

On model classes, update is an attribute of type +Update for massive updates, for +example:

await User.update.values(enabled=True).where(...).gino.status()
+

+

Like query, the update query also has the model execution +option of this model, so if you use the +returning() clause, the query shall +return model objects.

However on model instances, update() is a method which accepts keyword +arguments only and returns an UpdateRequest to update this single +model instance. The keyword arguments are pairs of attribute names and new +values. This is the same as UpdateRequest.update(), feel free to +read more about it. A normal usage example would be like this:

await user.update(name='new name', age=32).apply()
+

+

Here, the await ... apply() executes the +actual UPDATE SQL in the database, while user.update() only makes +changes in the memory, and collect all changes into an +UpdateRequest instance.

+ +

+class gino.crud.QueryModel¶

Bases: type

Metaclass of Model classes used for subqueries.

+ +

+class gino.crud.UpdateRequest(instance: gino.crud.CRUDModel)¶

Bases: object

A collection of attributes and their new values to update on one model +instance.

UpdateRequest instances are created by CRUDModel.update, +don’t instantiate manually unless required. Every UpdateRequest +instance is bound to one model instance, all updates are for that one +specific model instance and its database row.

+async apply(bind=None, timeout=<object object>)¶

Apply pending updates into database by executing an UPDATE SQL.

Parameters

bind – A GinoEngine to execute the SQL, or +None (default) to use the bound engine in the metadata.
timeout – Seconds to wait for the database to finish executing, +None for wait forever. By default it will use the timeout +execution option value if unspecified.

Returns

self for chaining calls.

+ +

+update(**values)¶

Set given attributes on the bound model instance, and add them into +the update collections for apply().

Given keyword-only arguments are pairs of attribute names and values to +update. This is not a coroutine, calling update() will have +instant effect on the bound model instance - its in-memory values will +be updated immediately. Therefore this can be used individually as a +shortcut to update several attributes in a batch:

user.update(age=32, disabled=True)
+

+

update() returns self for chaining calls to either +apply() or another update(). If one attribute is updated +several times by the same UpdateRequest, then only the last +value is remembered for apply().

Updated values can be SQLAlchemy expressions, for example an atomic +increment for user balance looks like this:

await user.update(balance=User.balance + 100).apply()
+

+

Note

Expression values will not affect the in-memory attribute value on +update() before apply(), because it has no knowledge +of the latest value in the database. After apply() the new +value will be automatically reloaded from database with +RETURNING clause.

+ +

+ + +

+ + + +
+ This work is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License. +

+ +

gino.crud module

+ + +

+ +

+ Add your language here. +

+ +

+ +

+ + + + + + + + + + + \ No newline at end of file diff --git a/docs/en/1.0/reference/api/gino.declarative.html b/docs/en/1.0/reference/api/gino.declarative.html new file mode 100644 index 0000000..b6c6c29 --- /dev/null +++ b/docs/en/1.0/reference/api/gino.declarative.html @@ -0,0 +1,382 @@ + + + + + + + + gino.declarative module - GINO 1.0.2.dev0 documentation + + + + + + + + + + + +

+ + +

Tutorials

How-to Guides

Explanation

Reference

Reference
- API Reference
- Extensions
- History
+
API Reference
- gino package
+
Extensions
History

+ +

gino.declarative module¶

+class gino.declarative.ColumnAttribute(prop_name, column)¶

Bases: object

The type of the column wrapper attributes on GINO models.

This is the core utility to enable GINO models so that:

Accessing a column attribute on a model class returns the column itself
Accessing a column attribute on a model instance returns the value for that column

This utility is customizable by defining __attr_factory__ in the model class.

+ +

+class gino.declarative.InvertDict(*args, **kwargs)¶

Bases: dict

A custom dict that allows getting keys by values.

Used internally by Model.

+invert_get(value, default=None)¶

Get key by value.

Parameters

value – A value in this dict.
default – If specified value doesn’t exist, return default.

Returns

The corresponding key if the value is found, or default otherwise.

+ +

+class gino.declarative.Model¶

Bases: object

The base class of GINO models.

This is not supposed to be sub-classed directly, declarative_base() should +be used instead to generate a base model class with a given +MetaData. By defining subclasses of a model, instances +of sqlalchemy.schema.Table will be created and added to the bound +MetaData. The columns of the +Table instance are defined as +Column attributes:

from sqlalchemy import MetaData, Column, Integer, String
+from gino.declarative import declarative_base
+
+Model = declarative_base()
+
+class User(db.Model):
+    __tablename__ = "users"
+    id = Column(Integer(), primary_key=True)
+    name = Column(String())
+

+

The name of the columns are automatically set using the attribute name.

An instance of a model will maintain a memory storage for values of all the defined +column attributes. You can access these values by the same attribute name, or update +with new values, just like normal Python objects:

u = User()
+assert u.name is None
+
+u.name = "daisy"
+assert u.name == "daisy"
+

+

Note

Accessing column attributes on a model instance will NOT trigger any database +operation.

Constraint and Index are +also allowed as model class attributes. Their attribute names are not used.

A concrete model class can be used as a replacement of the +Table it reflects in SQLAlchemy queries. The model class +is also iterable, yielding all the Column instances +defined in the model.

Other built-in class attributes:

__metadata__
+
This is supposed to be set by declarative_base() and used only during +subclass construction. Still, this can be treated as a read-only attribute to +find out which MetaData this model is bound to.
+
__tablename__
+
This is a required attribute to define a concrete model, meaning a +sqlalchemy.schema.Table instance will be created, added to the bound +MetaData and set to the class attribute __table__. +Not defining __tablename__ will result in an abstract model - no table +instance will be created, and instances of an abstract model are meaningless.
+
__table__
+
This should usually be treated as an auto-generated read-only attribute storing +the sqlalchemy.schema.Table instance.
+
__attr_factory__
+
An attribute factory that is used to wrap the actual +Column instance on the model class, so that the access +to the column attributes on model instances is redirected to the in-memory value +store. The default factory is ColumnAttribute, can be override.
+
__values__
+
The internal in-memory value store as a dict, only available on model +instances. Accessing column attributes is equivalent to accessing __values__.
+

+ +

+gino.declarative.declarative_base(metadata, model_classes=(<class 'gino.declarative.Model'>, ), name='Model')¶

Create a base GINO model class for declarative table definition.

Parameters

metadata – A MetaData instance to contain the +tables.
model_classes – Base class(es) of the base model class to be created. Default: +Model.
name – The class name of the base model class to be created. Default: +Model.

Returns

A new base model class.

+ +

+gino.declarative.declared_attr(m)¶

Mark a class-level method as a factory of attribute.

This is intended to be used as decorators on class-level methods of a +Model class. When initializing the class as well as its +subclasses, the decorated factory method will be called for each class, the +returned result will be set on the class in place of the factory method +under the same name.

@declared_attr is implemented differently than +declared_attr of SQLAlchemy, but they +are both more often used on mixins to dynamically declare indices or +constraints (also works for column and __table_args__, or even normal +class attributes):

class TrackedMixin:
+    created = db.Column(db.DateTime(timezone=True))
+
+    @db.declared_attr
+    def unique_id(cls):
+        return db.Column(db.Integer())
+
+    @db.declared_attr
+    def unique_constraint(cls):
+        return db.UniqueConstraint('unique_id')
+
+    @db.declared_attr
+    def poly(cls):
+        if cls.__name__ == 'Thing':
+            return db.Column(db.Unicode())
+
+    @db.declared_attr
+    def __table_args__(cls):
+        if cls.__name__ == 'Thing':
+            return db.UniqueConstraint('poly'),
+

+

Note

This doesn’t work if the model already had a __table__.

+ +

+ + +

+ + + +
+ This work is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License. +

+ +

gino.declarative module

+ + +

+ +

+ Add your language here. +

+ +

+ +

+ + + + + + + + + + + \ No newline at end of file diff --git a/docs/en/1.0/reference/api/gino.dialects.asyncpg.html b/docs/en/1.0/reference/api/gino.dialects.asyncpg.html new file mode 100644 index 0000000..082c144 --- /dev/null +++ b/docs/en/1.0/reference/api/gino.dialects.asyncpg.html @@ -0,0 +1,590 @@ + + + + + + + + gino.dialects.asyncpg module - GINO 1.0.2.dev0 documentation + + + + + + + + + + + +

+ + +

Tutorials

How-to Guides

Explanation

Reference

Reference
- API Reference
- Extensions
- History
+
API Reference
- gino package
+
Extensions
History

+ +

gino.dialects.asyncpg module¶

+class gino.dialects.asyncpg.AsyncEnum(*enums, **kw)¶

Bases: sqlalchemy.dialects.postgresql.base.ENUM

+async create_async(bind=None, checkfirst=True)¶

+ +

+async drop_async(bind=None, checkfirst=True)¶

+ +

+class gino.dialects.asyncpg.AsyncpgCompiler(dialect, statement, column_keys=None, inline=False, **kwargs)¶

Bases: sqlalchemy.dialects.postgresql.base.PGCompiler

+property bindtemplate¶

+ +

+class gino.dialects.asyncpg.AsyncpgCursor(context, cursor)¶

Bases: gino.dialects.base.Cursor

+async forward(n, *, timeout=<object object>)¶

+ +

+async many(n, *, timeout=<object object>)¶

+ +

+async next(*, timeout=<object object>)¶

+ +

+class gino.dialects.asyncpg.AsyncpgDBAPI¶

Bases: gino.dialects.base.BaseDBAPI

+Error = (<class 'asyncpg.exceptions._base.PostgresError'>, <class 'asyncpg.exceptions._base.InterfaceError'>)¶

+ +

+class gino.dialects.asyncpg.AsyncpgDialect(*args, **kwargs)¶

Bases: sqlalchemy.dialects.postgresql.base.PGDialect, gino.dialects.base.AsyncDialectMixin

+colspecs = {<class 'sqlalchemy.sql.sqltypes.ARRAY'>: <class 'sqlalchemy.dialects.postgresql.array.ARRAY'>, <class 'sqlalchemy.sql.sqltypes.Interval'>: <class 'sqlalchemy.dialects.postgresql.base.INTERVAL'>, <class 'sqlalchemy.sql.sqltypes.Enum'>: <class 'gino.dialects.asyncpg.AsyncEnum'>, <class 'sqlalchemy.sql.sqltypes.JSON.JSONPathType'>: <class 'gino.dialects.asyncpg.AsyncpgJSONPathType'>, <class 'sqlalchemy.sql.sqltypes.JSON'>: <class 'sqlalchemy.dialects.postgresql.json.JSON'>, <class 'sqlalchemy.dialects.postgresql.base.ENUM'>: <class 'gino.dialects.asyncpg.AsyncEnum'>, <class 'sqlalchemy.sql.sqltypes.NullType'>: <class 'gino.dialects.asyncpg.GinoNullType'>}¶

+ +

+cursor_cls¶: alias of DBAPICursor
+

+ +

+dbapi_class¶: alias of AsyncpgDBAPI
+

+ +

+driver = 'asyncpg'¶

+ +

+execution_ctx_cls¶: alias of AsyncpgExecutionContext
+

+ +

+async get_isolation_level(connection)¶: Given an asyncpg connection, return its isolation level.
+

+ +

+async has_schema(connection, schema)¶

+ +

+async has_sequence(connection, sequence_name, schema=None)¶

Check the existence of a particular sequence in the database.

Given a _engine.Connection object and a string +sequence_name, return True if the given sequence exists in +the database, False otherwise.

+ +

+async has_table(connection, table_name, schema=None)¶

Check the existence of a particular table in the database.

Given a _engine.Connection object and a string +table_name, return True if the given table (possibly within +the specified schema) exists in the database, False +otherwise.

+ +

+async has_type(connection, type_name, schema=None)¶

+ +

+init_kwargs = {'command_timeout', 'connection_class', 'database', 'host', 'init', 'loop', 'max_cacheable_statement_size', 'max_cached_statement_lifetime', 'max_inactive_connection_lifetime', 'max_queries', 'max_size', 'min_size', 'passfile', 'password', 'port', 'server_settings', 'setup', 'ssl', 'statement_cache_size', 'timeout', 'user'}¶

+ +

+async init_pool(url, loop, pool_class=None)¶

+ +

+on_connect()¶

return a callable which sets up a newly created DBAPI connection.

The callable should accept a single argument “conn” which is the +DBAPI connection itself. The inner callable has no +return value.

E.g.:

class MyDialect(default.DefaultDialect):
+    # ...
+
+    def on_connect(self):
+        def do_on_connect(connection):
+            connection.execute("SET SPECIAL FLAGS etc")
+
+        return do_on_connect
+

+

This is used to set dialect-wide per-connection options such as +isolation modes, Unicode modes, etc.

The “do_on_connect” callable is invoked by using the +_events.PoolEvents.first_connect() and +_events.PoolEvents.connect() event +hooks, then unwrapping the DBAPI connection and passing it into the +callable. The reason it is invoked for both events is so that any +dialect-level initialization that occurs upon first connection, which +also makes use of the _events.PoolEvents.first_connect() method, +will +proceed after this hook has been called. This currently means the +hook is in fact called twice for the very first connection in which a +dialect creates; and once per connection afterwards.

If None is returned, no event listener is generated.

Returns: a callable that accepts a single DBAPI connection as an +argument, or None.
+

See also

Dialect.connect() - allows the DBAPI connect() sequence +itself to be controlled.

+ +

+async set_isolation_level(connection, level)¶: Given an asyncpg connection, set its isolation level.
+

+ +

+statement_compiler¶: alias of AsyncpgCompiler
+

+ +

+supports_native_decimal = True¶

+ +

+transaction(raw_conn, args, kwargs)¶

+ +

+class gino.dialects.asyncpg.AsyncpgExecutionContext¶: Bases: gino.dialects.base.ExecutionContextOverride, sqlalchemy.dialects.postgresql.base.PGExecutionContext
+

+ +

+class gino.dialects.asyncpg.AsyncpgIterator(context, iterator)¶: Bases: object
+

+ +

+class gino.dialects.asyncpg.AsyncpgJSONPathType¶

Bases: sqlalchemy.dialects.postgresql.json.JSONPathType

+bind_processor(dialect)¶

Return a conversion function for processing bind values.

Returns a callable which will receive a bind parameter value +as the sole positional argument and will return a value to +send to the DB-API.

If processing is not necessary, the method should return None.

Parameters: dialect – Dialect instance in use.
+

+ +

+class gino.dialects.asyncpg.DBAPICursor(dbapi_conn)¶

Bases: gino.dialects.base.DBAPICursor

+async async_execute(query, timeout, args, limit=0, many=False)¶

+ +

+property description¶

+ +

+get_statusmsg()¶

+ +

+async prepare(context, clause=None)¶

+ +

+class gino.dialects.asyncpg.GinoNullType¶

Bases: sqlalchemy.sql.sqltypes.NullType

+result_processor(dialect, coltype)¶

Return a conversion function for processing result row values.

Returns a callable which will receive a result row column +value as the sole positional argument and will return a value +to return to the user.

If processing is not necessary, the method should return None.

Parameters

dialect – Dialect instance in use.
coltype – DBAPI coltype argument received in cursor.description.

+ +

+class gino.dialects.asyncpg.NullPool(url, loop, **kwargs)¶

+async acquire(*, timeout=None)¶

+ +

+async close()¶

+ +

+property raw_pool¶

+ +

+async release(conn)¶

+ +

+repr(color)¶

+ +

+class gino.dialects.asyncpg.Pool(url, loop, **kwargs)¶

+async acquire(*, timeout=None)¶

+ +

+async close()¶

+ +

+property raw_pool¶

+ +

+async release(conn)¶

+ +

+repr(color)¶

+ +

+class gino.dialects.asyncpg.PreparedStatement(prepared, clause=None)¶: Bases: gino.dialects.base.PreparedStatement
+

+ +

+class gino.dialects.asyncpg.Transaction(tx)¶

Bases: gino.dialects.base.Transaction

+async begin()¶

+ +

+async commit()¶

+ +

+property raw_transaction¶

+ +

+async rollback()¶

+ +

+ + +

+ + + +
+ This work is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License. +

+ +

gino.dialects.asyncpg module

+ + +

+ +

+ Add your language here. +

+ +

+ +

+ + + + + + + + + + + \ No newline at end of file diff --git a/docs/en/1.0/reference/api/gino.dialects.base.html b/docs/en/1.0/reference/api/gino.dialects.base.html new file mode 100644 index 0000000..3e4d14e --- /dev/null +++ b/docs/en/1.0/reference/api/gino.dialects.base.html @@ -0,0 +1,449 @@ + + + + + + + + gino.dialects.base module - GINO 1.0.2.dev0 documentation + + + + + + + + + + + +

+ + +

Tutorials

How-to Guides

Explanation

Reference

Reference
- API Reference
- Extensions
- History
+
API Reference
- gino package
+
Extensions
History

+ +

gino.dialects.base module¶

+class gino.dialects.base.AsyncDialectMixin¶

Bases: object

+compile(elem, *multiparams, **params)¶

+ +

+cursor_cls¶: alias of DBAPICursor
+

+ +

+classmethod dbapi()¶

+ +

+dbapi_class¶: alias of BaseDBAPI
+

+ +

+async init_pool(url, loop)¶

+ +

+transaction(raw_conn, args, kwargs)¶

+ +

+class gino.dialects.base.BaseDBAPI¶

Bases: object

+static Binary(x)¶

+ +

+Error¶: alias of builtins.Exception
+

+ +

+paramstyle = 'numeric'¶

+ +

+class gino.dialects.base.Cursor¶

Bases: object

+async forward(n, *, timeout=<object object>)¶

+ +

+async many(n, *, timeout=<object object>)¶

+ +

+async next(*, timeout=<object object>)¶

+ +

+class gino.dialects.base.DBAPICursor¶

Bases: object

+async async_execute(query, timeout, args, limit=0, many=False)¶

+ +

+property description¶

+ +

+execute(statement, parameters)¶

+ +

+executemany(statement, parameters)¶

+ +

+get_statusmsg()¶

+ +

+async prepare(context, clause=None)¶

+ +

+class gino.dialects.base.ExecutionContextOverride¶

Bases: object

+get_result_proxy()¶

+ +

+loader¶

+ +

+model¶

+ +

+process_rows(rows, return_model=True)¶

+ +

+return_model¶

+ +

+timeout¶

+ +

+class gino.dialects.base.Pool¶

Bases: object

+async acquire(*, timeout=None)¶

+ +

+async close()¶

+ +

+property raw_pool¶

+ +

+async release(conn)¶

+ +

+repr(color)¶

+ +

+class gino.dialects.base.PreparedStatement(clause=None)¶

Bases: object

+async all(*multiparams, **params)¶

+ +

+async first(*multiparams, **params)¶

+ +

+iterate(*params, **kwargs)¶

+ +

+async scalar(*multiparams, **params)¶

+ +

+async status(*multiparams, **params)¶

+ +

+class gino.dialects.base.Transaction¶

Bases: object

+async begin()¶

+ +

+async commit()¶

+ +

+property raw_transaction¶

+ +

+async rollback()¶

+ +

+ + +

+ + + +
+ This work is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License. +

+ +

gino.dialects.base module

+ + +

+ +

+ Add your language here. +

+ +

+ +

+ + + + + + + + + + + \ No newline at end of file diff --git a/docs/en/1.0/reference/api/gino.dialects.html b/docs/en/1.0/reference/api/gino.dialects.html new file mode 100644 index 0000000..ec7f8dd --- /dev/null +++ b/docs/en/1.0/reference/api/gino.dialects.html @@ -0,0 +1,223 @@ + + + + + + + + gino.dialects package - GINO 1.0.2.dev0 documentation + + + + + + + + + + + +

+ + +

Tutorials

How-to Guides

Explanation

Reference

Reference
- API Reference
- Extensions
- History
+
API Reference
- gino package
+
Extensions
History

+ +

gino.dialects package¶

Submodules¶

Module contents¶

+ + +

+ + + +
+ This work is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License. +

+ +

gino.dialects package
- Submodules
- Module contents
+

+ + +

+ +

+ Add your language here. +

+ +

+ +

+ + + + + + + + + + + \ No newline at end of file diff --git a/docs/en/1.0/reference/api/gino.engine.html b/docs/en/1.0/reference/api/gino.engine.html new file mode 100644 index 0000000..e4b9927 --- /dev/null +++ b/docs/en/1.0/reference/api/gino.engine.html @@ -0,0 +1,715 @@ + + + + + + + + gino.engine module - GINO 1.0.2.dev0 documentation + + + + + + + + + + + +

+ + +

Tutorials

How-to Guides

Explanation

Reference

Reference
- API Reference
- Extensions
- History
+
API Reference
- gino package
+
Extensions
History

+ +

gino.engine module¶

+class gino.engine.GinoConnection(dialect, sa_conn, stack=None)¶

Bases: object

Represents an actual database connection.

This is the root of all query API like all(), first(), +one(), one_or_none(), scalar() or status(), +those on engine or query are simply wrappers of methods in this class.

Usually instances of this class are created by GinoEngine.acquire().

Note

GinoConnection may refer to zero or one underlying database +connection - when a GinoConnection is acquired with +lazy=True, the underlying connection may still be in the pool, +until a query API is called or get_raw_connection() is called.

Oppositely, one underlying database connection can be shared by many +GinoConnection instances when they are acquired with +reuse=True. The actual database connection is only returned to the +pool when the root GinoConnection is released. Read more +in GinoEngine.acquire() method.

See also

+async all(clause, *multiparams, **params)¶

Runs the given query in database, returns all results as a list.

This method accepts the same parameters taken by SQLAlchemy +execute(). You can pass in a raw +SQL string, or any SQLAlchemy query clauses.

If the given query clause is built by CRUD models, then the returning +rows will be turned into relevant model objects (Only one type of model +per query is supported for now, no relationship support yet). See +execution_options() for more information.

If the given parameters are parsed as “executemany” - bulk inserting +multiple rows in one call for example, the returning result from +database will be discarded and this method will return None.

+ +

+property dialect¶: The Dialect in use, inherited +from the engine created this connection.
+

+ +

+execution_options(**opt)¶

Set non-SQL options for the connection which take effect during +execution.

This method returns a copy of this GinoConnection which +references the same underlying database connection, but with the given +execution options set on the copy. Therefore, it is a good practice to +discard the copy immediately after use, for example:

row = await conn.execution_options(model=None).first(User.query)
+

+

This is very much the same as SQLAlchemy +execution_options(), it +actually does pass the execution options to the underlying SQLAlchemy +Connection. Furthermore, GINO added a +few execution options:

Parameters

return_model – Boolean to control whether the returning results +should be loaded into model instances, where the model class is +defined in another execution option model. Default is True.
model – Specifies the type of model instance to create on return. +This has no effect if return_model is set to False. Usually +in queries built by CRUD models, this execution option is +automatically set. For now, GINO only supports loading each row into +one type of model object, relationships are not supported. Please use +multiple queries for that. None for no postprocessing (default).
timeout – Seconds to wait for the query to finish. None for +no time out (default).
loader –
A loader expression to load the database rows into +specified objective structure. It can be either:
+
- A model class, so that the query will yield model instances of this +class. It is your responsibility to make sure all the columns of +this model is selected in the query.
- A Column instance, so that each result +will be only a single value of this column. Please note, if you +want to achieve fetching the very first value, you should use +first() instead of +scalar(). However, using directly +scalar() is a more direct way.
- A tuple nesting more loader expressions recursively.
- A callable() function that will be called for each row to +fully customize the result. Two positional arguments will be passed +to the function: the first is the row instance, the second is a context +object which is only present if nested else None.
- A Loader instance directly.
- Anything else will be treated as literal values thus returned as +whatever they are.
+

+ +

+async first(clause, *multiparams, **params)¶

Runs the given query in database, returns the first result.

If the query returns no result, this method will return None.

See all() for common query comments.

+ +

+async get_raw_connection(*, timeout=None)¶

Get the underlying database connection, acquire one if none present.

Parameters: timeout – Seconds to wait for the underlying acquiring
+
Returns: Underlying database connection instance depending on the +dialect in use
+
Raises: TimeoutError if the acquiring timed out
+

+ +

+iterate(clause, *multiparams, **params)¶

Creates a server-side cursor in database for large query results.

Cursors must work within transactions:

async with conn.transaction():
+    async for user in conn.iterate(User.query):
+        # handle each user without loading all users into memory
+

+

Alternatively, you can manually control how the cursor works:

async with conn.transaction():
+    cursor = await conn.iterate(User.query)
+    user = await cursor.next()
+    users = await cursor.many(10)
+

+

See also

+ +

+async scalar(clause, *multiparams, **params)¶

Runs the given query in database, returns the first result.

If the query returns no result, this method will return None.

See all() for common query comments.

+ +

+schema_for_object = <sqlalchemy.sql.schema._SchemaTranslateMap object>¶: A SQLAlchemy compatibility attribute, don’t use it for now, it bites.
+

+ +

+async status(clause, *multiparams, **params)¶

Runs the given query in database, returns the query status.

The returning query status depends on underlying database and the +dialect in use. For asyncpg it is a string, you can parse it like this: +https://git.io/v7oze

+ +

+transaction(*args, **kwargs)¶

Starts a database transaction.

There are two ways using this method: managed as an asynchronous +context manager:

async with conn.transaction() as tx:
+    # run query in transaction
+

+

or manually awaited:

tx = await conn.transaction()
+try:
+    # run query in transaction
+    await tx.commit()
+except Exception:
+    await tx.rollback()
+    raise
+

+

Where the tx is an instance of the +GinoTransaction class, feel free to read +more about it.

In the first managed mode, the transaction is automatically committed +on exiting the context block, or rolled back if an exception was raised +which led to the exit of the context. In the second manual mode, you’ll +need to manually call the +commit() or +rollback() methods on need.

If this is a lazy connection, entering a transaction will cause a new +database connection acquired if none was present.

Transactions may support nesting depending on the dialect in use. For +example in asyncpg, starting a second transaction on the same +connection will create a save point in the database.

For now, the parameters are directly passed to underlying database +driver, read asyncpg.connection.Connection.transaction() for +asyncpg.

+ +

+class gino.engine.GinoEngine(dialect, pool, loop, logging_name=None, echo=None, execution_options=None)¶

Bases: object

Connects a Pool and +Dialect together to provide a source +of database connectivity and behavior.

A GinoEngine object is instantiated publicly using the +gino.create_engine() function or +db.set_bind() method.

See also

+acquire(*, timeout=None, reuse=False, lazy=False, reusable=True)¶

Acquire a connection from the pool.

There are two ways using this method - as an asynchronous context +manager:

async with engine.acquire() as conn:
+    # play with the connection
+

+

which will guarantee the connection is returned to the pool when +leaving the async with block; or as a coroutine:

conn = await engine.acquire()
+try:
+    # play with the connection
+finally:
+    await conn.release()
+

+

where the connection should be manually returned to the pool with +conn.release().

Within the same context (usually the same Task, see +also Transaction), a nesting acquire by default re

Parameters

timeout – Block up to timeout seconds until there is one free +connection in the pool. Default is None - block forever until +succeeded. This has no effect when lazy=True, and depends on the +actual situation when reuse=True.
reuse – Reuse the latest reusable acquired connection (before +it’s returned to the pool) in current context if there is one, or +borrow a new one if none present. Default is False for always +borrow a new one. This is useful when you are in a nested method call +series, wishing to use the same connection without passing it around +as parameters. See also: Transaction. A reusing +connection is not reusable even if reusable=True. If the reused +connection happened to be a lazy one, then the reusing connection is +lazy too.
lazy – Don’t acquire the actual underlying connection yet - do it +only when needed. Default is False for always do it immediately. +This is useful before entering a code block which may or may not make +use of a given connection object. Feeding in a lazy connection will +save the borrow-return job if the connection is never used. If +setting reuse=True at the same time, then the reused connection - +if any - applies the same laziness. For example, reusing a lazy +connection with lazy=False will cause the reused connection to +acquire an underlying connection immediately.
reusable – Mark this connection as reusable or otherwise. This +has no effect if it is a reusing connection. All reusable connections +are placed in a stack, any reusing acquire operation will always +reuse the top (latest) reusable connection. One reusable connection +may be reused by several reusing connections - they all share one +same underlying connection. Acquiring a connection with +reusable=False and reusing=False makes it a cleanly isolated +connection which is only referenced once here.

Returns

A GinoConnection object.

+ +

+async all(clause, *multiparams, **params)¶

Acquires a connection with reuse=True and runs +all() on it. reuse=True means you can safely +do this without borrowing more than one underlying connection:

async with engine.acquire():
+    await engine.all('SELECT ...')
+

+

The same applies for other query methods.

+ +

+async close()¶: Close the engine, by closing the underlying pool.
+

+ +

+compile(clause, *multiparams, **params)¶: A shortcut for compile() on +the dialect, returns raw SQL string and parameters according to the +rules of the dialect.
+

+ +

+connection_cls¶

Customizes the connection class to use, default is +GinoConnection.

alias of GinoConnection

+ +

+property current_connection¶

Gets the most recently acquired reusable connection in the context. +None if there is no such connection.

Returns: GinoConnection
+

+ +

+property dialect¶: Read-only property for the +Dialect of this engine.
+

+ +

+async first(clause, *multiparams, **params)¶: Runs first(), See all().
+

+ +

+iterate(clause, *multiparams, **params)¶

Creates a server-side cursor in database for large query results.

This requires that there is a reusable connection in the current +context, and an active transaction is present. Then its +GinoConnection.iterate() is executed and returned.

+ +

+async one(clause, *multiparams, **params)¶: Runs one(), See all().
+

+ +

+async one_or_none(clause, *multiparams, **params)¶: Runs one_or_none(), See all().
+

+ +

+property raw_pool¶: Read-only access to the underlying database connection pool instance. +This depends on the actual dialect in use, Pool +of asyncpg for example.
+

+ +

+repr(color=False)¶

+ +

+async scalar(clause, *multiparams, **params)¶: Runs scalar(), See all().
+

+ +

+async status(clause, *multiparams, **params)¶: Runs status(). See also all().
+

+ +

+transaction(*args, timeout=None, reuse=True, reusable=True, **kwargs)¶

Borrows a new connection and starts a transaction with it.

Different to GinoConnection.transaction(), transaction on engine +level supports only managed usage:

async with engine.transaction() as tx:
+    # play with transaction here
+

+

Where the implicitly acquired connection is available as +tx.connection.

By default, transaction() acquires connection with +reuse=True and reusable=True, that means it by default tries to +create a nested transaction instead of a new transaction on a new +connection. You can change the default behavior by setting these two +arguments.

The other arguments are the same as +transaction() on connection.

See also

GinoConnection.transaction()

GinoTransaction

Returns: A asynchronous context manager that yields a +GinoTransaction
+

+ +

+update_execution_options(**opt)¶: Update the default execution_options dictionary +of this GinoEngine.
+
+
See also
+
sqlalchemy.engine.Engine.update_execution_options()
+
GinoConnection.execution_options()
+
+

+ +

+ + +

+ + + +
+ This work is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License. +

+ +

gino.engine module

+ + +

+ +

+ Add your language here. +

+ +

+ +

+ + + + + + + + + + + \ No newline at end of file diff --git a/docs/en/1.0/reference/api/gino.exceptions.html b/docs/en/1.0/reference/api/gino.exceptions.html new file mode 100644 index 0000000..ee6b333 --- /dev/null +++ b/docs/en/1.0/reference/api/gino.exceptions.html @@ -0,0 +1,241 @@ + + + + + + + + gino.exceptions module - GINO 1.0.2.dev0 documentation + + + + + + + + + + + +

+ + +

Tutorials

How-to Guides

Explanation

Reference

Reference
- API Reference
- Extensions
- History
+
API Reference
- gino package
+
Extensions
History

+ +

gino.exceptions module¶

+exception gino.exceptions.GinoException¶: Bases: Exception
+

+ +

+exception gino.exceptions.MultipleResultsFound¶: Bases: gino.exceptions.GinoException
+

+ +

+exception gino.exceptions.NoResultFound¶: Bases: gino.exceptions.GinoException
+

+ +

+exception gino.exceptions.NoSuchRowError¶: Bases: gino.exceptions.GinoException
+

+ +

+exception gino.exceptions.UninitializedError¶: Bases: gino.exceptions.GinoException
+

+ +

+exception gino.exceptions.UnknownJSONPropertyError¶: Bases: gino.exceptions.GinoException
+

+ +

+ + +

+ + + +
+ This work is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License. +

+ +

gino.exceptions module

+ + +

+ +

+ Add your language here. +

+ +

+ +

+ + + + + + + + + + + \ No newline at end of file diff --git a/docs/en/1.0/reference/api/gino.ext.html b/docs/en/1.0/reference/api/gino.ext.html new file mode 100644 index 0000000..b3d560b --- /dev/null +++ b/docs/en/1.0/reference/api/gino.ext.html @@ -0,0 +1,224 @@ + + + + + + + + gino.ext package - GINO 1.0.2.dev0 documentation + + + + + + + + + + + +

+ + +

Tutorials

How-to Guides

Explanation

Reference

Reference
- API Reference
- Extensions
- History
+
API Reference
- gino package
+
Extensions
History

+ +

gino.ext package¶

Module contents¶

Namespace package for GINO extensions.

This namespace package didn’t use any of the 3 official solutions. Instead, +gino.ext adds a hook into sys.meta_path, and utilize the Entry points +to find the extensions.

Any GINO extension package should provide an entry point like this:

[gino.extensions]
+starlette = gino_starlette
+

+

So that the Python package gino_starlette will also be importable through +gino.ext.starlette.

+ + +

+ + + +
+ This work is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License. +

+ +

gino.ext package
- Module contents
+

+ + +

+ +

+ Add your language here. +

+ +

+ +

+ + + + + + + + + + + \ No newline at end of file diff --git a/docs/en/1.0/reference/api/gino.html b/docs/en/1.0/reference/api/gino.html new file mode 100644 index 0000000..f463d46 --- /dev/null +++ b/docs/en/1.0/reference/api/gino.html @@ -0,0 +1,262 @@ + + + + + + + + gino package - GINO 1.0.2.dev0 documentation + + + + + + + + + + + +

+ + +

Tutorials

How-to Guides

Explanation

Reference

Reference
- API Reference
- Extensions
- History
+
API Reference
- gino package
+
Extensions
History

+ +

gino package¶

Subpackages¶

gino.dialects package
- Submodules
  - gino.dialects.asyncpg module
  - gino.dialects.base module
  +
- Module contents
+
gino.ext package
- Module contents
+

Submodules¶

Module contents¶

+gino.create_engine(*args, **kwargs)¶: Shortcut for sqlalchemy.create_engine() with strategy="gino".
+

+ +

+gino.get_version()¶: Get current GINO version.
+

+ +

+ + +

+ + + +
+ This work is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License. +

+ +

gino package
- Subpackages
- Submodules
- Module contents
+

+ + +

+ +

+ Add your language here. +

+ +

+ +

+ + + + + + + + + + + \ No newline at end of file diff --git a/docs/en/1.0/reference/api/gino.json_support.html b/docs/en/1.0/reference/api/gino.json_support.html new file mode 100644 index 0000000..1008c74 --- /dev/null +++ b/docs/en/1.0/reference/api/gino.json_support.html @@ -0,0 +1,347 @@ + + + + + + + + gino.json_support module - GINO 1.0.2.dev0 documentation + + + + + + + + + + + +

+ + +

Tutorials

How-to Guides

Explanation

Reference

Reference
- API Reference
- Extensions
- History
+
API Reference
- gino package
+
Extensions
History

+ +

gino.json_support module¶

+class gino.json_support.ArrayProperty(default=None, prop_name='profile')¶

+decode(val)¶

+ +

+encode(val)¶

+ +

+class gino.json_support.BooleanProperty(default=None, prop_name='profile')¶

+decode(val)¶

+ +

+encode(val)¶

+ +

+make_expression(base_exp)¶

+ +

+class gino.json_support.DateTimeProperty(default=None, prop_name='profile')¶

+decode(val)¶

+ +

+encode(val)¶

+ +

+make_expression(base_exp)¶

+ +

+class gino.json_support.IntegerProperty(default=None, prop_name='profile')¶

+decode(val)¶

+ +

+encode(val)¶

+ +

+make_expression(base_exp)¶

+ +

+class gino.json_support.JSONProperty(default=None, prop_name='profile')¶

Bases: object

+decode(val)¶

+ +

+encode(val)¶

+ +

+get_profile(instance)¶

+ +

+make_expression(base_exp)¶

+ +

+reload(instance)¶

+ +

+save(instance, value=<object object>)¶

+ +

+class gino.json_support.ObjectProperty(default=None, prop_name='profile')¶

+decode(val)¶

+ +

+encode(val)¶

+ +

+class gino.json_support.StringProperty(default=None, prop_name='profile')¶

+make_expression(base_exp)¶

+ +

+ + +

+ + + +
+ This work is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License. +

+ +

gino.json_support module

+ + +

+ +

+ Add your language here. +

+ +

+ +

+ + + + + + + + + + + \ No newline at end of file diff --git a/docs/en/1.0/reference/api/gino.loader.html b/docs/en/1.0/reference/api/gino.loader.html new file mode 100644 index 0000000..546740d --- /dev/null +++ b/docs/en/1.0/reference/api/gino.loader.html @@ -0,0 +1,630 @@ + + + + + + + + gino.loader module - GINO 1.0.2.dev0 documentation + + + + + + + + + + + +

+ + +

Tutorials

How-to Guides

Explanation

Reference

Reference
- API Reference
- Extensions
- History
+
API Reference
- gino package
+
Extensions
History

+ +

gino.loader module¶

+class gino.loader.AliasLoader(alias, *columns, **extras)¶

Bases: gino.loader.ModelLoader

The same as ModelLoader, kept for compatibility.

+ +

+class gino.loader.CallableLoader(func)¶

Load the row by calling a specified function.

Parameters: func – A callable() taking 2 positional arguments (row, context) +that will be called in do_load(), returning the loaded result.
+

+do_load(row, context)¶

Interface used by GINO to run the loader.

The arguments are simply passed to the given function.

Parameters

row – A RowProxy instance.
context – A dict that is reused across all loaders in one query.

Returns

The result calling the given function, followed by True.

+ +

+class gino.loader.ColumnLoader(column)¶

Load a given column in the row.

Parameters: column – The column name as str, or a +Column instance to avoid name conflict.
+

+do_load(row, context)¶

Interface used by GINO to run the loader.

Parameters

row – A RowProxy instance.
context – Not used.

Returns

The value of the specified column, followed by True.

+ +

+class gino.loader.Loader¶

Bases: object

The abstract base class of loaders.

Loaders are used to load raw database rows into expected results. +GinoEngine will use the loader set on the loader value of +the execution_options(), for example:

from sqlalchemy import text, create_engine
+from gino.loader import ColumnLoader
+
+e = await create_engine("postgresql://localhost/gino", strategy="gino")
+q = text("SELECT now() as ts")
+loader = ColumnLoader("ts")
+ts = await e.first(q.execution_options(loader=loader))  # datetime
+

+

+do_load(row, context)¶

Interface used by GINO to run the loader.

Must be implemented in subclasses.

Parameters

row – A RowProxy instance.
context – A dict that is reused across all loaders in one query.

Returns

Any result that the loader is supposed to return, followed by a boolean +value indicating if the result is distinct.

+ +

+classmethod get(value)¶

Automatically create a loader based on the type of the given value.

+ ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

value type	loader type
`tuple`	`TupleLoader`
`callable()`	`CallableLoader`
`Column`, +`Label`	`ColumnLoader`
`Model`	`ModelLoader`
`Alias`	`AliasLoader`
`Loader`	as is
any other types	`ValueLoader`

Parameters: value – Any supported value above.
+
Returns: A loader instance.
+

+ +

+get_columns()¶

Generate a list of selectables from this loader.

This is an experimental feature, this method is supposed to be called by +query.

Returns: A list of SQLAlchemy selectables.
+

+ +

+get_from()¶

Generate a clause to be used in +select_from() from this loader.

This is an experimental feature, this method is supposed to be called by +query.

Returns: A FromClause instance, or None.
+

+ +

+property query¶

Generate a query from this loader.

This is an experimental feature, not all loaders support this.

Returns: A query instance with the loader execution option set to self.
+

+ +

+class gino.loader.ModelLoader(model, *columns, **extras)¶

A loader that loads a row into a GINO model instance.

This loader generates an instance of the given model type and fills the instance +with attributes according to the other given parameters:

Load each column attribute listed in the given columns positional arguments.
If columns is not given, all defined columns of the model will be loaded.
For each keyword argument, its value will be used to generate a loader using +Loader.get(), and the loaded value will be setattr() to the model +instance under the name of the key.

For example, the simplest select and load:

sqlalchemy.select([User]).execution_options(loader=ModelLoader(User))
+

+

Select only the name column, and still load it into model instances:

sqlalchemy.select(
+    [User.name]
+).execution_options(
+    loader=ModelLoader(User, User.name)
+)
+

+

This would also yield User instances, with all column attributes as None but +name.

Nest a ValueLoader:

sqlalchemy.select(
+    [User.name]
+).execution_options(
+    loader=ModelLoader(User, id=1)
+)
+

+

1 is then converted into a ValueLoader and mocked the id attribute +of all returned User instances as 1.

Nest another ModelLoader:

sqlalchemy.select(
+    [user.outerjoin(Company)]
+).execution_options(
+    loader=ModelLoader(User, company=Company)
+)
+

+

Likewise, Company is converted into a ModelLoader to load the +Company columns from the joined result, and the Company instances are set to +the company attribute of each User instance using setattr().

Parameters

model – A subclass of Model to instantiate.
columns – A list of Column or str to +load, default is all the columns in the model.
extras – Additional attributes to load on the model instance.

+distinct(*columns)¶

Configure this loader to reuse instances that have the same values of all the +give columns.

Parameters: columns – Preferably Column instances.
+
Returns: self for chaining.
+

+ +

+do_load(row, context)¶

Interface used by GINO to run the loader.

Parameters

row – A RowProxy instance.
context – A dict that is reused across all loaders in one query.

Returns

The model instance, followed by a boolean value indicating if the +result is distinct.

+ +

+get_columns()¶

Generate a list of selectables from this loader.

This is an experimental feature, this method is supposed to be called by +query.

Returns: A list of SQLAlchemy selectables.
+

+ +

+get_from()¶

Generate a clause to be used in +select_from() from this loader.

This is an experimental feature, this method is supposed to be called by +query.

Returns: A FromClause instance, or None.
+

+ +

+load(*columns, **extras)¶

Update the loader with new rules.

After initialization, the rules of this loader can still be updated. This is +useful when using the model class as a shortcut of ModelLoader where +possible, chaining with a load() to initialize the rules, for example:

sqlalchemy.select(
+    [user.outerjoin(Company)]
+).execution_options(
+    loader=ModelLoader(User, company=Company.load('name'))
+)
+

+

Parameters

columns – If provided, replace the columns to load with the given ones.
extras – Update the loader with new extras.

Returns

self for chaining.

+ +

+none_as_none(enabled=True)¶: Deprecated method for compatibility, does nothing.
+

+ +

+on(on_clause)¶

Specify the on_clause for generating joined queries.

This is an experimental feature, used by get_from().

Parameters: on_clause – An expression to feed into +join().
+
Returns: self for chaining.
+

+ +

+class gino.loader.TupleLoader(values)¶

Load multiple values into a tuple.

Parameters: values – A tuple, each item is converted into a loader with +Loader.get().
+

+do_load(row, context)¶

Interface used by GINO to run the loader.

The arguments are simply passed to sub-loaders.

Parameters

row – A RowProxy instance.
context – A dict that is reused across all loaders in one query.

Returns

A tuple with loaded results from all sub-loaders, followed by +True.

+ +

+class gino.loader.ValueLoader(value)¶

A loader that always return the specified value.

Parameters: value – The value to return on load.
+

+do_load(row, context)¶

Interface used by GINO to run the loader.

Parameters

row – Not used.
context – Not used.

Returns

The given value, followed by True.

+ +

+ + +

+ + + +
+ This work is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License. +

+ +

gino.loader module

+ + +

+ +

+ Add your language here. +

+ +

+ +

+ + + + + + + + + + + \ No newline at end of file diff --git a/docs/en/1.0/reference/api/gino.schema.html b/docs/en/1.0/reference/api/gino.schema.html new file mode 100644 index 0000000..04f0159 --- /dev/null +++ b/docs/en/1.0/reference/api/gino.schema.html @@ -0,0 +1,325 @@ + + + + + + + + gino.schema module - GINO 1.0.2.dev0 documentation + + + + + + + + + + + +

+ + +

Tutorials

How-to Guides

Explanation

Reference

Reference
- API Reference
- Extensions
- History
+
API Reference
- gino package
+
Extensions
History

+ +

gino.schema module¶

+class gino.schema.AsyncSchemaDropper(dialect, connection, checkfirst=False, tables=None, **kwargs)¶

Bases: gino.schema.AsyncVisitor, sqlalchemy.sql.ddl.SchemaDropper

+async visit_foreign_key_constraint(constraint)¶

+ +

+async visit_index(index)¶

+ +

+async visit_metadata(metadata)¶

+ +

+async visit_sequence(sequence, drop_ok=False)¶

+ +

+async visit_table(table, drop_ok=False, _is_metadata_operation=False)¶

+ +

+class gino.schema.AsyncSchemaGenerator(dialect, connection, checkfirst=False, tables=None, **kwargs)¶

Bases: gino.schema.AsyncVisitor, sqlalchemy.sql.ddl.SchemaGenerator

+async visit_foreign_key_constraint(constraint)¶

+ +

+async visit_index(index)¶

+ +

+async visit_metadata(metadata)¶

+ +

+async visit_sequence(sequence, create_ok=False)¶

+ +

+async visit_table(table, create_ok=False, include_foreign_key_constraints=None, _is_metadata_operation=False)¶

+ +

+class gino.schema.AsyncSchemaTypeMixin¶

Bases: object

+async create_async(bind=None, checkfirst=False)¶

+ +

+async drop_async(bind=None, checkfirst=False)¶

+ +

+class gino.schema.AsyncVisitor¶

Bases: object

+async traverse_single(obj, **kw)¶

+ +

+class gino.schema.GinoSchemaVisitor(item)¶

Bases: object

+async create(bind=None, *args, **kwargs)¶

+ +

+async create_all(bind=None, tables=None, checkfirst=True)¶

+ +

+async drop(bind=None, *args, **kwargs)¶

+ +

+async drop_all(bind=None, tables=None, checkfirst=True)¶

+ +

+gino.schema.patch_schema(db)¶

+ +

+ + +

+ + + +
+ This work is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License. +

+ +

gino.schema module

+ + +

+ +

+ Add your language here. +

+ +

+ +

+ + + + + + + + + + + \ No newline at end of file diff --git a/docs/en/1.0/reference/api/gino.strategies.html b/docs/en/1.0/reference/api/gino.strategies.html new file mode 100644 index 0000000..ecdae0a --- /dev/null +++ b/docs/en/1.0/reference/api/gino.strategies.html @@ -0,0 +1,233 @@ + + + + + + + + gino.strategies module - GINO 1.0.2.dev0 documentation + + + + + + + + + + + +

+ + +

Tutorials

How-to Guides

Explanation

Reference

Reference
- API Reference
- Extensions
- History
+
API Reference
- gino package
+
Extensions
History

+ +

gino.strategies module¶

+class gino.strategies.GinoStrategy¶

Bases: sqlalchemy.engine.strategies.EngineStrategy

A SQLAlchemy engine strategy for GINO.

This strategy is initialized automatically as gino is imported.

If sqlalchemy.create_engine() uses strategy="gino", it will return a +Coroutine, and treat URL prefix postgresql:// or +postgres:// as postgresql+asyncpg://.

+async create(name_or_url, loop=None, **kwargs)¶: Given arguments, returns a new Engine instance.
+

+ +

+engine_cls¶: alias of gino.engine.GinoEngine
+

+ +

+name = 'gino'¶

+ +

+ + +

+ + + +
+ This work is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License. +

+ +

gino.strategies module

+ + +

+ +

+ Add your language here. +

+ +

+ +

+ + + + + + + + + + + \ No newline at end of file diff --git a/docs/en/1.0/reference/api/gino.transaction.html b/docs/en/1.0/reference/api/gino.transaction.html new file mode 100644 index 0000000..12b04a8 --- /dev/null +++ b/docs/en/1.0/reference/api/gino.transaction.html @@ -0,0 +1,329 @@ + + + + + + + + gino.transaction module - GINO 1.0.2.dev0 documentation + + + + + + + + + + + +

+ + +

Tutorials

How-to Guides

Explanation

Reference

Reference
- API Reference
- Extensions
- History
+
API Reference
- gino package
+
Extensions
History

+ +

gino.transaction module¶

+class gino.transaction.GinoTransaction(conn, args, kwargs)¶

Bases: object

Represents an underlying database transaction and its connection, offering +methods to manage this transaction.

GinoTransaction is supposed to be created by either +gino.engine.GinoConnection.transaction(), or +gino.engine.GinoEngine.transaction(), or +gino.api.Gino.transaction(), shown as follows:

async with db.transaction() as tx:
+    ...
+
+async with engine.transaction() as tx:
+    ...
+
+async with conn.transaction() as tx:
+    ...
+
+tx = await conn.transaction()
+try:
+    ...
+    await tx.commit()
+except Exception:
+    await tx.rollback()
+    raise
+

+

When in use with asynchronous context manager, GinoTransaction +will be in managed mode, while the last example with await will put +the GinoTransaction in manual mode where you have to call +the commit() or rollback() to manually close the transaction.

In managed mode the transaction will be automatically committed or +rolled back on exiting the async with block depending on whether there +is an exception or not. Meanwhile, you can explicitly exit the transaction +early by raise_commit() or raise_rollback() which will raise +an internal exception managed by the asynchronous context manager and +interpreted as a commit or rollback action. In a nested transaction +situation, the two exit-early methods always close up the very transaction +which the two methods are referenced upon - all children transactions are +either committed or rolled back correspondingly, while no parent +transaction was ever touched. For example:

async with db.transaction() as tx1:
+    async with db.transaction() as tx2:
+        async with db.transaction() as tx3:
+            tx2.raise_rollback()
+            # Won't reach here
+        # Won't reach here
+    # Continues here with tx1, with both tx2 and tx3 rolled back.
+
+    # For PostgreSQL, tx1 can still be committed successfully because
+    # tx2 and tx3 are just SAVEPOINTs in transaction tx1
+

+

Tip

The internal exception raised from raise_commit() and +raise_rollback() is a subclass of BaseException, so +normal try ... except Exception: can’t trap the commit or rollback.

+async commit()¶: Only available in manual mode: manually commit this transaction.
+

+ +

+property connection¶: Accesses to the GinoConnection of this +transaction. This is useful if when the transaction is started from +db or engine where the connection is implicitly acquired for +you together with the transaction.
+

+ +

+raise_commit()¶

Only available in managed mode: skip rest of the code in this +transaction and commit immediately by raising an internal exception, +which will be caught and handled by the asynchronous context manager:

async with db.transaction() as tx:
+    await user.update(age=64).apply()
+    tx.raise_commit()
+    await user.update(age=32).apply()  # won't reach here
+
+assert user.age == 64  # no exception raised before
+

+

+ +

+raise_rollback()¶

Only available in managed mode: skip rest of the code in this +transaction and rollback immediately by raising an internal exception, +which will be caught and handled by the asynchronous context manager:

assert user.age == 64  # assumption
+
+async with db.transaction() as tx:
+    await user.update(age=32).apply()
+    tx.raise_rollback()
+    await user.update(age=128).apply()  # won't reach here
+
+assert user.age == 64  # no exception raised before
+

+

+ +

+property raw_transaction¶: Accesses to the underlying transaction object, whose type depends on +the dialect in use.
+

+ +

+async rollback()¶: Only available in manual mode: manually rollback this transaction.
+

+ +

+ + +

+ + + +
+ This work is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License. +

+ +

gino.transaction module

+ + +

+ +

+ Add your language here. +

+ +

+ +

+ + + + + + + + + + + \ No newline at end of file diff --git a/docs/en/1.0/reference/extensions.html b/docs/en/1.0/reference/extensions.html new file mode 100644 index 0000000..4859b34 --- /dev/null +++ b/docs/en/1.0/reference/extensions.html @@ -0,0 +1,217 @@ + + + + + + + + Extensions - GINO 1.0.2.dev0 documentation + + + + + + + + + + + +

+ +

+ + + + + + + +

+ + + +

+ + HOME + + + CREDITS + + +

Tutorials

How-to Guides

Explanation

Reference

Reference
- API Reference
- Extensions
- History
+
API Reference
Extensions
- Sanic Support
- Starlette Support
- Tornado Support
+
History

+ +

Extensions¶

Sanic Support
- Work with Sanic
- Sanic Support
+
Starlette Support
- Work with Starlette
- Configuration
- Lazy Connection
+
Tornado Support

+ + +

+ + + +
+ This work is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License. +

+ +

Extensions

+ + +

+ +

+ Add your language here. +

+ +

+ +

+ + + + + + + + + + + \ No newline at end of file diff --git a/docs/en/1.0/reference/extensions/sanic.html b/docs/en/1.0/reference/extensions/sanic.html new file mode 100644 index 0000000..e9e3a98 --- /dev/null +++ b/docs/en/1.0/reference/extensions/sanic.html @@ -0,0 +1,326 @@ + + + + + + + + Sanic Support - GINO 1.0.2.dev0 documentation + + + + + + + + + + + +

+ + +

Tutorials

How-to Guides

Explanation

Reference

Reference
- API Reference
- Extensions
- History
+
API Reference
Extensions
- Sanic Support
- Starlette Support
- Tornado Support
+
History

+ +

Sanic Support¶

THIS IS A WIP

Work with Sanic¶

Using the Sanic extension, the request handler acquires a lazy connection on each request, +and return the connection when the response finishes by default.

The lazy connection is actually established if necessary, i.e. just before first access to db.

This behavior is controlled by app.config.DB_USE_CONNECTION_FOR_REQUEST, which is True by default.

Supported configurations:

DB_HOST
DB_PORT
DB_USER
DB_PASSWORD
DB_DATABASE
DB_ECHO
DB_POOL_MIN_SIZE
DB_POOL_MAX_SIZE
DB_USE_CONNECTION_FOR_REQUEST
DB_KWARGS

An example server:

from sanic import Sanic
+from sanic.exceptions import abort
+from sanic.response import json
+from gino.ext.sanic import Gino
+
+app = Sanic()
+app.config.DB_HOST = 'localhost'
+app.config.DB_DATABASE = 'gino'
+db = Gino()
+db.init_app(app)
+
+
+class User(db.Model):
+    __tablename__ = 'users'
+
+    id = db.Column(db.BigInteger(), primary_key=True)
+    nickname = db.Column(db.Unicode())
+
+    def __repr__(self):
+        return '{}<{}>'.format(self.nickname, self.id)
+
+
+@app.route("/users/<user_id>")
+async def get_user(request, user_id):
+    if not user_id.isdigit():
+        abort(400, 'invalid user id')
+    user = await User.get_or_404(int(user_id))
+    return json({'name': user.nickname})
+
+
+if __name__ == '__main__':
+    app.run(debug=True)
+

+

Sanic Support¶

To integrate with Sanic, a few configurations needs to be set in +app.config (with default value though):

DB_HOST: if not set, localhost
DB_PORT: if not set, 5432
DB_USER: if not set, postgres
DB_PASSWORD: if not set, empty string
DB_DATABASE: if not set, postgres
DB_ECHO: if not set, False
DB_POOL_MIN_SIZE: if not set, 5
DB_POOL_MAX_SIZE: if not set, 10
DB_KWARGS; if not set, empty dictionary

An example:

from sanic import Sanic
+from gino.ext.sanic import Gino
+
+app = Sanic()
+app.config.DB_HOST = 'localhost'
+app.config.DB_USER = 'postgres'
+
+db = Gino()
+db.init_app(app)
+

+

After db.init_app, a connection pool with configured settings shall be +created and bound to db when Sanic server is started, and closed on stop. +Furthermore, a lazy connection context is created on each request, and released +on response. That is to say, within Sanic request handlers, you can directly +access db by e.g. User.get(1), everything else is settled: database pool is +created on server start, connection is lazily borrowed from pool on the first +database access and shared within the rest of the same request handler, and +automatically returned to the pool on response.

Please be noted that, in the async world, await may block unpredictably for +a long time. When this world is crossing RDBMS pools and transactions, it is +a very dangerous bite for performance, even causing disasters sometimes. +Therefore we recommend, during the time enjoying fast development, do pay +special attention to the scope of transactions and borrowed connections, make +sure that transactions are closed as soon as possible, and connections are not +taken for unnecessarily long time. As for the Sanic support, if you want to +release the concrete connection in the request context before response is +reached, just do it like this:

await request['connection'].release()
+

+

Or if you prefer not to use the contextual lazy connection in certain handlers, +prefer explicitly manage the connection lifetime, you can always borrow a new +connection by setting reuse=False:

async with db.acquire(reuse=False):
+    # new connection context is created
+

+

Or if you prefer not to use the builtin request-scoped lazy connection at all, +you can simply turn it off:

app.config.DB_USE_CONNECTION_FOR_REQUEST = False
+

+

+ + +

+ + + +
+ This work is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License. +

+ +

Sanic Support
- Work with Sanic
- Sanic Support
+

+ + +

+ +

+ Add your language here. +

+ +

+ +

+ + + + + + + + + + + \ No newline at end of file diff --git a/docs/en/1.0/reference/extensions/starlette.html b/docs/en/1.0/reference/extensions/starlette.html new file mode 100644 index 0000000..4e91e68 --- /dev/null +++ b/docs/en/1.0/reference/extensions/starlette.html @@ -0,0 +1,323 @@ + + + + + + + + Starlette Support - GINO 1.0.2.dev0 documentation + + + + + + + + + + + +

+ + +

Tutorials

How-to Guides

Explanation

Reference

Reference
- API Reference
- Extensions
- History
+
API Reference
Extensions
- Sanic Support
- Starlette Support
- Tornado Support
+
History

+ +

Starlette Support¶

Work with Starlette¶

To use GINO with Starlette, the gino-starlette package should +be installed first:

pip install gino-starlette
+

+

Note

The gino-starlette package supports only GINO 1.0 or later. +Earlier versions of GINO like 0.8.x have built-in Starlette support.

This extension provides a Starlette middleware to setup and cleanup +database according to the configurations that passed in the kwargs +parameter.

The common usage looks like this:

from starlette.applications import Starlette
+from gino.ext.starlette import Gino
+
+app = Starlette()
+db = Gino(app, **kwargs)
+
+# Or with application factory
+app = Starlette()
+db = Gino(**kwargs)
+db.init_app(app)
+

+

Configuration¶

The config includes:

+ +++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

Name	Description	Default
`driver`	the database driver	`asyncpg`
`host`	database server host	`localhost`
`port`	database server port	`5432`
`user`	database server user	`postgres`
`password`	database server password	empty
`database`	database name	`postgres`
`dsn`	a SQLAlchemy database URL to create the engine, its existence will replace all previous connect arguments.	N/A
`pool_min_size`	the initial number of connections of the db pool.	N/A
`pool_max_size`	the maximum number of connections in the db pool.	N/A
`echo`	enable SQLAlchemy echo mode.	N/A
`ssl`	SSL context passed to `asyncpg.connect`	`None`
`use_connection_for_request`	flag to set up lazy connection for requests.	N/A
`kwargs`	other parameters passed to the specified dialects, like `asyncpg`. Unrecognized parameters will cause exceptions.	N/A

Lazy Connection¶

If use_connection_for_request is set to be True, then a lazy +connection is available at request['connection']. By default, a +database connection is borrowed on the first query, shared in the same +execution context, and returned to the pool on response. If you need to +release the connection early in the middle to do some long-running +tasks, you can simply do this:

await request['connection'].release(permanent=False)
+

+

+ + +

+ + + +
+ This work is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License. +

+ +

Starlette Support
- Work with Starlette
- Configuration
- Lazy Connection
+

+ + +

+ +

+ Add your language here. +

+ +

+ +

+ + + + + + + + + + + \ No newline at end of file diff --git a/docs/en/1.0/reference/extensions/tornado.html b/docs/en/1.0/reference/extensions/tornado.html new file mode 100644 index 0000000..a384a81 --- /dev/null +++ b/docs/en/1.0/reference/extensions/tornado.html @@ -0,0 +1,205 @@ + + + + + + + + Tornado Support - GINO 1.0.2.dev0 documentation + + + + + + + + + + + +

+ + +

Tutorials

How-to Guides

Explanation

Reference

Reference
- API Reference
- Extensions
- History
+
API Reference
Extensions
- Sanic Support
- Starlette Support
- Tornado Support
+
History

+ +

Tornado Support¶

THIS IS A WIP

+ + +

+ + + +
+ This work is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License. +

+ +

Tornado Support

+ + +

+ +

+ Add your language here. +

+ +

+ +

+ + + + + + + + + + + \ No newline at end of file diff --git a/docs/en/1.0/reference/history.html b/docs/en/1.0/reference/history.html new file mode 100644 index 0000000..b14167d --- /dev/null +++ b/docs/en/1.0/reference/history.html @@ -0,0 +1,900 @@ + + + + + + + + History - GINO 1.0.2.dev0 documentation + + + + + + + + + + + +

+ +

+ + + + + + + +

+ + + +

+ + HOME + + + CREDITS + + +

Tutorials

How-to Guides

Explanation

Reference

Reference
- API Reference
- Extensions
- History
+
API Reference
Extensions
History

+ +

History¶

GINO 1.0¶

Migrating to GINO 1.0¶

GINO 1.0 moved the built-in Web framework extensions into separate PyPI +packages. If you’re using one of them, you should install GINO 1.0 with extras:

+ ++++ + + + + + + + + + + + + + + + + + + + + + + +

Extension Module	Installation in GINO 1.0
`gino.ext.starlette`	`pip install gino[starlette]`
`gino.ext.aiohttp`	`pip install gino[aiohttp]`
`gino.ext.sanic`	`pip install gino[sanic]`
`gino.ext.tornado`	`pip install gino[tornado]`
`gino.ext.quart`	`pip install gino[quart]`

The new extension packages are backward-compatible, so there’s no need to +update the import statements. For example, this will still work in GINO 1.0 if +you installed gino[starlette]:

from gino.ext.starlette import Gino
+

+

GINO 1.0 switched to Poetry for package and +dependency management and started to use the +src layout. This shouldn’t +cause any problem using GINO as a dependency, but it does introduce some +changes to the GINO development process:

Source files are now located under src directory.
The src dist on PyPI does not include tests, docs and some other files due to +a limitation of Poetry.

1.0.1 (2020-06-08)¶

Fixed dependency version range (SQLAlchemy >=1.2.16, <1.4)
Updated docs (Including contribution by Galden in #660, and Iuliia Volkova in #672)
Multiple JSON property fixes (#661 #662 #695)
Fixed extension typing issue (#673 #674)
Fixed model override behavior (#694)
Fixed multiple JSON profiles issue (Contributed by Roman Averchenkov in #693 #696)

1.0.0 (2020-04-26)¶

Switched to Poetry for package and dependency management.
[Breaking] Moved built-in extension modules to separate PyPI packages.
Switched to src layout.
Switched to black code style.
Better documentation.
[Breaking] none_as_none() is now always enabled.
Added representation method for engine.
Protected the URL instance fed to set_bind() from manipulation.
Replaced some assert with AssertionError (#258 #655)

GINO 0.8¶

This is also version 1.0 release candidate.

Migrating to GINO 0.8¶

1. contextvars¶

We introduced aiocontextvars 0.2.0 which is revamped to be compatible with +PEP-567 without manual interference by a few simple implicit patches. To +upgrade to GINO 0.8, please remove the enable_inherit() or +disable_inherit() calls, because they are the default behavior now thus +no longer exist. However, you’ll need to confirm that the event loop in use is +always created after importing gino or aiocontextvars, or the patch +won’t work correctly.

There is nothing to worry about in Python 3.7.

2. none_as_none¶

When GINO tries to load a row with all NULL values into an instance, it +will now by default return None instead of an instance with all None +attributes. To recover the default behavior of 0.7, please specify +none_as_none(False) in affected model loader.

This is especially applicable to relationship sub-loaders - if the sub-loader +found it all NULL, no instance will be set to parent instance. For +example:

child = await Child.load(parent=Parent).query.gino.first()
+

+

If child.parent_id is NULL in database, then the child instance +won’t be called with any setattr(child, 'parent', ...) at all. (If you need +child.parent == None in this case, consider setting default value +parent = None in child model.)

Please note, it is deprecated to disable none_as_none, and disabling will +be removed in GINO 1.0.

0.8.7 (2020-04-19)¶

Improved error handling when attribute names collide (Contributed by Reskov in #637 #638)
Fixed with_bind usability in aiohttp extension (#518)

0.8.6 (2020-02-10)¶

Fixed JSONPathType bind processor for asyncpg (#609)
Allowed for primary keys with different names from the database columns (Contributed by Tiago Requeijo in #599 #600)
Allowed to use simple callable instead of property for one-2-many loading (Contributed by Olexiy in #629)
Added distinct() to Alias (#628)

0.8.5 (2019-11-19)¶

Improved support for __tablename__ in declared_attr (Contributed by Roald Storm in #592)

0.8.4 (2019-11-09)¶

Better loader support for models in subqueries (#573 #585)
Allowed __tablename__ to be a declared_attr (#579 #582)
Fixed Sanic 19.9.0 compatibility (#569)
Added one() and one_or_none() (Contributed by Ilaï Deutel in #577)
Improved Starleet extension compatibility (Contributed by Jim O’Brien in #538)
Fixed Starlette connection release during exceptions issue (Contributed by qulaz in #533)
Fixed server event compatibility with Sanic 19.6.2 (Contributed by Julio Lacerda in #520)
Fixed Grammar (Contributed by Simeon J Morgan in #504)

0.8.3 (2019-06-06)¶

Fixed deprecated warnings in asyncpg dialect and aiohttp (#425)
Customizable db attribute name in aiohttp app instance (#457)
Added Starlette support (#486)

0.8.2 (2019-03-07)¶

Added exception for unknown JSON properties (#406 #408)
Supported Quart 0.7 (#411)
Accepted kwargs for db init in extensions (#407 #427)
Added custom config parameter to aiohttp middleware (Contributed by Michał Dziewulski in #440)
Added NullPool (#437 #441)
Unpinned dependency versions (#447)
Added support for SQLAlchemy 1.3 (#433 #451)

0.8.1 (2018-12-08)¶

Alias supported Label (#365)
Docs update (#308, 4c59ad, #401 by Pascal van Kooten)
Version requirement for SQLAlchemy is updated to >=1.2 (#378 #382)
Added option for SSL in aiohttp extension (Contributed by Martin Zaťko in #387 #393) +* And all other extensions (#395)
Supported Tornado 5 (#396, also thanks to Vladimir Goncharov)
Fixed custom JSON/JSONB type support (#402 #403)

(Most fixes done by Tony Wang)

0.8.0 (2018-10-16)¶

Welcome Tony Wang to the maintenance team (#335)
Allowed custom column names (#261 #297)
Allowed column instance in model.load() (Contributed by Jekel in #323)
[Breaking] Upgraded to aiocontextvars 0.2.0 (#333)
Fixed bug that the same empty stack is shared between sub-tasks (#313 #334)
[Breaking] Made none_as_none() the default behavior (#351)
Bug fixes and docs update

GINO 0.7¶

This is also version 1.0 beta 3.

0.7.7 (2018-12-08)¶

Backported fix for custom JSON/JSONB type support (#402 #403)

0.7.6 (2018-08-26)¶

Updated library support (Contributed by Tony Wang in #275 #309)
Added none_as_none() (#281 #282)
Added ARRAY alias in asyncpg dialect module (Contributed by Mykyta Holubakha in #289)
Added Model.lookup() to prevent updating whole table without primary key (#287 #288)
Added DB_ECHO in extension options (Contributed by Mykyta Holubakha in #298)
Fixed broken JSON/JSONB result processor since 0.5.8 (Contributed by Tony Wang in #291 #305)
Removed bad rollback after a failing commit (Contributed by Tony Wang in #302 #304)
Fixed to raise UninitializedError if bind is None (Contributed by Tony Wang in #307 #310)

0.7.5 (2018-07-26)¶

Added friendly error message when using abstract models by mistake (#224)
Supported Python 3.7 (Contributed by Tony Wang in #265)
Updated documentation
Fixed a bug in TupleLoader (Contributed by Pavol Vargovcik in #279 #280)

0.7.4 (2018-06-10)¶

Added aiocontextvars as required dependency required for Python 3.5 and 3.6 (#228)
Added Quart support (#213)
Fixed Tornado options parsing (#231)
Improved coding style and test coverage

0.7.3 (2018-05-19)¶

Fix for failing binary type (#225)

0.7.2 (2018-05-15)¶

Added prepared statement support (#14)
Added dsn in extension config (Contributed by Yurii Shtrikker in #215)

0.7.1 (2018-05-03)¶

Added support for inline model constraints (Contributed by Kinware in #198)
Added docs and tests for using SSL (#202)
Added declared_attr (#204)
Allowed ModelLoader passively load partial model (#216)

0.7.0 (2018-04-18)¶

Added Python 3.5 support (#187)
Added support to use dict as ident for Model.get (#192)
Added result loader (partial relationship support) (#13)
Added documentation on relationship and transaction (#146)

GINO 0.6¶

This is also version 1.0 beta 2.

Migrating to GINO 0.6¶

1. Task Local¶

We created a new Python package aiocontextvars from previous local.py. If +you made use of the task local features, you should install this package.

Previous gino.enable_task_local() and gino.disable_task_local() are +replaced by aiocontextvars.enable_inherit() and +aiocontextvars.disable_inherit(). However in GINO 0.5 they controls the +whole task local feature switch, while aiocontextvars by default offers task +local even without enable_inherit(), which controls whether the local +storage should be passed between chained tasks. When enabled, it behaves the +same as enabled in 0.5, but you cannot completely turn off the task local +feature while aiocontextvars is installed.

There is no gino.get_local() and gino.reset_local() relevant in +aiocontextvars. The similar thing is aiocontextvars.ContextVar instance +through its get(), set() and delete() methods.

Previous gino.is_local_root() is now +not aiocontextvars.Context.current().inherited.

2. Engine¶

GINO 0.6 hides asyncpg.Pool behind the new SQLAlchemy-alike +gino.GinoEngine. Instead of doing this in 0.5:

async with db.create_pool('postgresql://...') as pool:
+    # your code here
+

+

You should change it to this in 0.6:

async with db.with_bind('postgresql://...') as engine:
+    # your code here
+

+

This equals to:

engine = await gino.create_engine('postgresql://...')
+db.bind = engine
+try:
+    # your code here
+finally:
+    db.bind = None
+    await engine.close()
+

+

Or:

engine = await db.set_bind('postgresql://...')
+try:
+    # your code here
+finally:
+    await db.pop_bind().close()
+

+

Or even this:

db = await gino.Gino('postgresql://...')
+try:
+    # your code here
+finally:
+    await db.pop_bind().close()
+

+

Choose whichever suits you the best.

Obviously GinoEngine doesn’t provide asyncpg.Pool methods directly any +longer, but you can get the underlying asyncpg.Pool object through +engine.raw_pool property.

GinoPool.get_current_connection() is now changed to current_connection +property on GinoEngine instances to support multiple engines.

GinoPool.execution_option is gone, instead update_execution_options() +on GinoEngine instance is available.

GinoPool().metadata is gone, dialect is still available.

GinoPool.release() is removed in GinoEngine and Gino, the +release() method on GinoConnection object should be used instead.

These methods exist both in 0.5 GinoPool and 0.6 GinoEngine: +close(), acquire(), all(), first(), scalar(), status().

3. GinoConnection¶

Similarly, GinoConnection in 0.6 is no longer a subclass of +asyncpg.Connection, instead it has a asyncpg.Connection instance, +accessable through GinoConnection.raw_connection property.

GinoConnection.metadata is deleted in 0.6, while dialect remained.

GinoConnection.execution_options() is changed from a mutable dict in 0.5 to +a method returning a copy of current connection with the new options, the same +as SQLAlchemy behavior.

GinoConnection.release() is still present, but its default behavior has +been changed to permanently release this connection. You should add argument +permanent=False to remain its previous behavior.

And all(), first(), scalar(), status(), iterate(), +transaction() remained in 0.6.

4. Query API¶

All five query APIs all(), first(), scalar(), status(), +iterate() now accept the same parameters as SQLAlchemy execute(), +meaning they accept raw SQL text, or multiple sets of parameters for +“executemany”. Please note, if the parameters are recognized as “executemany”, +none of the methods will return anything. Meanwhile, they no longer accept the +parameter bind if they did. Just use the API on the GinoEngine or +GinoConnection object instead.

5. Transaction¶

Transaction interface is rewritten. Now in 0.6, a GinoTransaction object is +provided consistently from all 3 methods:

async with db.transaction() as tx:
+    # within transaction
+
+async with engine.transaction() as tx:
+    # within transaction
+
+async with engine.acquire() as conn:
+    async with conn.transaction() as tx:
+        # within transaction
+

+

And different usage with await:

tx = await db.transaction()
+try:
+    # within transaction
+    await tx.commit()
+except:
+    await tx.rollback()
+    raise
+

+

The GinoConnection object is available at tx.connection, while +underlying transaction object from database driver is available at +tx.transaction - for asyncpg it is an asyncpg.transaction.Transaction +object.

0.6.6 (2018-05-18)¶

Backported a fix for failing binary type (#225)

0.6.5 (2018-04-18)¶

Abandoned 0.6.4 and keep 0.6.x stable
Backported doc for transaction

0.6.4 (2018-04-16)¶

Abandoned version, please use 0.7.0 instead.

0.6.3 (2018-04-08)¶

Added aiohttp support
Added support for calling create() on model instances (Contributed by Kinware in #178 #180)
Fixed get() by string, and misc environment issues (Contributed by Tony Wang in #191 193 #183 #184)

0.6.2 (2018-03-24)¶

Fixed SQLAlchemy prefetch issue (#141)
Fixed issue that mixin class on Model not working (#174)
Added more documentation (Thanks Olaf Conradi for reviewing)

0.6.1 (2018-03-18)¶

Fixed create and drop for Enum type (#160)
A bit more documentation (#159)

0.6.0 (2018-03-14)¶

[Breaking] API Refactored, Pool replaced with Engine
+
- New API Engine replaced asyncpg Pool (#59)
- Supported different dialects, theoretically
- Used aiocontextvars instead of builtin task local (#89)
+
[Breaking] Fixed query API with multiparams (executemany) to return correctly (#20)
[Breaking] The query methods no longer accept the parameter bind
[Breaking] Gino no longer exposes postgresql types
Added echo on engine (#142)
Added tests to cover 80% of code
Added gino extension on SchemaItem for create_all and so on (#76 #106)
Added gino extension on model classes for create() or drop()
Added _update_request_cls on CRUDModel (#147)
Rewrote the documentation (#146)

GINO 0.5¶

This is also version 1.0 beta 1.

0.5.8 (2018-02-14)¶

Preparing for 0.6.0 which will be a breaking release
Fixed wrong value of Enum in creation (Contributed by Sergey Kovalev in #126)

0.5.7 (2017-11-24)¶

This is an emergency fix for 0.5.6.

Fixed broken lazy connection (Contributed by Ádám Barancsuk in #114)
Added Model.outerjoin

0.5.6 (2017-11-23)¶

Changed to use unnamed statement when possible (#80 #90)
Added more example (Contributed by Kentoseth in #109)
Added Model.join and made Model selectable (Contributed by Ádám Barancsuk in #112 #113)

0.5.5 (2017-10-18)¶

Ensured clean connection if transaction acquire fails (Contributed by Vladimir Goncharov in #87)
Added ability to reset local storage (#84)
Fixed bug in JSON property update
Added update chaining feature

0.5.4 (2017-10-04)¶

Updated example (Contributed by Kinware in #75)
Added Model.insert (Contributed by Neal Wang in #63)
Fixed issue that non-lazy acquiring fails dirty (#79)

0.5.3 (2017-09-23)¶

Fixed no module named cutils error (Contributed by Vladimir Goncharov in #73)

0.5.2 (2017-09-10)¶

Added missing driver name on dialect (#67)
Fixed dialect to support native decimal type (#67)

0.5.1 (2017-09-09)¶

This is an emergency fix for 0.5.0.

Reverted the extension, back to pure Python (#60)
Used SQLAlchemy RowProxy
Added first_or_404
Fixed bug that GinoPool cannot be inherited

0.5.0 (2017-09-03)¶

[Breaking] Internal refactor: extracted and isolated a few modules, partially rewritten
+
- Extracted CRUD operations
- Core operations are moved to dialect and execution context
- Removed guess_model, switched to explicit execution options
- Turned timeout parameter to an execution option
- Extracted pool, connection and api from asyncpg_delegate
+
Added support for SQLAlchemy execution options, and a few custom options
[Breaking] Made Model.select return rows by default (#39)
Moved get_or_404 to extensions (#38)
Added iterator on model classes (#43)
Added Tornado extension (Contributed by Vladimir Goncharov)
Added Model.to_dict (#47)
Added an extension module to update asyncpg.Record with processed results

Early Development Releases¶

Considered as alpha releases.

0.4.1 (2017-08-20)¶

Support select on model instance

0.4.0 (2017-08-15)¶

Made get_or_404 more friendly when Sanic is missing (Contributed by Neal Wang in #23 #31)
Delegated sqlalchemy.__all__ (Contributed by Neal Wang in #10 #33)
[Breaking] Rewrote JSON/JSONB support (#29)
Added lazy parameter on db.acquire (Contributed by Binghan Li in #32)
Added Sanic integration (Contributed by Binghan Li, Tony Wang in #30 #32 #34)
Fixed iterate API to be compatible with asyncpg (#32)
Unified exceptions
[Breaking] Changed update API (#29)
Bug fixes

0.3.0 (2017-08-07)¶

Supported __table_args__ (#12)
Introduced task local to manage connection in context (#19)
Added query.gino extension for in-place execution
Refreshed README (#3)
Adopted PEP 487 (Contributed by Tony Wang in #17 #27)
Used weakref on __model__ of table and query (Contributed by Tony Wang)
Delegated asyncpg timeout parameter (Contributed by Neal Wang in #16 #22)

0.2.3 (2017-08-04)¶

Supported any primary key (Contributed by Tony Wang in #11)

0.2.2 (2017-08-02)¶

Supported SQLAlchemy result processor
Added rich support on JSON/JSONB
Bug fixes

0.2.1 (2017-07-28)¶

Added update and delete API

0.2.0 (2017-07-28)¶

Changed API, no longer reuses asyncpg API

0.1.1 (2017-07-25)¶

Added db.bind
API changed: parameter conn renamed to optional bind
Delegated asyncpg Pool with db.create_pool
Internal enhancement and bug fixes

0.1.0 (2017-07-21)¶

First release on PyPI.

+ + +

+ + + +
+ This work is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License. +

+ +

History
- GINO 1.0
  +
- GINO 0.8
  - Migrating to GINO 0.8
    - 1. contextvars
    - 2. none_as_none
    +
  - 0.8.7 (2020-04-19)
  - 0.8.6 (2020-02-10)
  - 0.8.5 (2019-11-19)
  - 0.8.4 (2019-11-09)
  - 0.8.3 (2019-06-06)
  - 0.8.2 (2019-03-07)
  - 0.8.1 (2018-12-08)
  - 0.8.0 (2018-10-16)
  +
- GINO 0.7
  +
- GINO 0.6
  - Migrating to GINO 0.6
    - 1. Task Local
    - 2. Engine
    - 3. GinoConnection
    - 4. Query API
    - 5. Transaction
    +
  - 0.6.6 (2018-05-18)
  - 0.6.5 (2018-04-18)
  - 0.6.4 (2018-04-16)
  - 0.6.3 (2018-04-08)
  - 0.6.2 (2018-03-24)
  - 0.6.1 (2018-03-18)
  - 0.6.0 (2018-03-14)
  +
- GINO 0.5
  +
- Early Development Releases
  +
+

+ + +

+ +

+ Add your language here. +

+ +

+ +

+ + + + + + + + + + + \ No newline at end of file diff --git a/docs/en/1.0/search.html b/docs/en/1.0/search.html new file mode 100644 index 0000000..2500d6c --- /dev/null +++ b/docs/en/1.0/search.html @@ -0,0 +1 @@ +

search.html

\ No newline at end of file diff --git a/docs/en/1.0/searchindex.js b/docs/en/1.0/searchindex.js new file mode 100644 index 0000000..28e6197 --- /dev/null +++ b/docs/en/1.0/searchindex.js @@ -0,0 +1 @@ +Search.setIndex({docnames:["explanation","explanation/async","explanation/engine","explanation/why","how-to","how-to/alembic","how-to/contributing","how-to/crud","how-to/faq","how-to/json-props","how-to/loaders","how-to/pool","how-to/schema","how-to/transaction","index","reference","reference/api","reference/api/gino","reference/api/gino.aiocontextvars","reference/api/gino.api","reference/api/gino.crud","reference/api/gino.declarative","reference/api/gino.dialects","reference/api/gino.dialects.asyncpg","reference/api/gino.dialects.base","reference/api/gino.engine","reference/api/gino.exceptions","reference/api/gino.ext","reference/api/gino.json_support","reference/api/gino.loader","reference/api/gino.schema","reference/api/gino.strategies","reference/api/gino.transaction","reference/extensions","reference/extensions/sanic","reference/extensions/starlette","reference/extensions/tornado","reference/history","tutorials","tutorials/announcement","tutorials/fastapi","tutorials/tutorial"],envversion:{"sphinx.domains.c":2,"sphinx.domains.changeset":1,"sphinx.domains.citation":1,"sphinx.domains.cpp":3,"sphinx.domains.index":1,"sphinx.domains.javascript":2,"sphinx.domains.math":2,"sphinx.domains.python":2,"sphinx.domains.rst":2,"sphinx.domains.std":1,"sphinx.ext.intersphinx":1,sphinx:56},filenames:["explanation.rst","explanation/async.rst","explanation/engine.rst","explanation/why.rst","how-to.rst","how-to/alembic.rst","how-to/contributing.rst","how-to/crud.rst","how-to/faq.rst","how-to/json-props.rst","how-to/loaders.rst","how-to/pool.rst","how-to/schema.rst","how-to/transaction.rst","index.rst","reference.rst","reference/api.rst","reference/api/gino.rst","reference/api/gino.aiocontextvars.rst","reference/api/gino.api.rst","reference/api/gino.crud.rst","reference/api/gino.declarative.rst","reference/api/gino.dialects.rst","reference/api/gino.dialects.asyncpg.rst","reference/api/gino.dialects.base.rst","reference/api/gino.engine.rst","reference/api/gino.exceptions.rst","reference/api/gino.ext.rst","reference/api/gino.json_support.rst","reference/api/gino.loader.rst","reference/api/gino.schema.rst","reference/api/gino.strategies.rst","reference/api/gino.transaction.rst","reference/extensions.rst","reference/extensions/sanic.rst","reference/extensions/starlette.rst","reference/extensions/tornado.rst","reference/history.rst","tutorials.rst","tutorials/announcement.rst","tutorials/fastapi.rst","tutorials/tutorial.rst"],objects:{"":{gino:[17,0,0,"-"]},"gino.aiocontextvars":{patch_asyncio:[18,1,1,""]},"gino.api":{Gino:[19,2,1,""],GinoExecutor:[19,2,1,""]},"gino.api.Gino":{Model:[19,3,1,""],acquire:[19,3,1,""],all:[19,3,1,""],bind:[19,3,1,""],compile:[19,3,1,""],first:[19,3,1,""],iterate:[19,3,1,""],model_base_classes:[19,4,1,""],no_delegate:[19,4,1,""],one:[19,3,1,""],one_or_none:[19,3,1,""],pop_bind:[19,3,1,""],query_executor:[19,4,1,""],scalar:[19,3,1,""],schema_visitor:[19,4,1,""],set_bind:[19,3,1,""],status:[19,3,1,""],transaction:[19,3,1,""],with_bind:[19,3,1,""]},"gino.api.GinoExecutor":{all:[19,3,1,""],first:[19,3,1,""],iterate:[19,3,1,""],load:[19,3,1,""],model:[19,3,1,""],one:[19,3,1,""],one_or_none:[19,3,1,""],query:[19,3,1,""],return_model:[19,3,1,""],scalar:[19,3,1,""],status:[19,3,1,""],timeout:[19,3,1,""]},"gino.crud":{Alias:[20,2,1,""],CRUDModel:[20,2,1,""],QueryModel:[20,2,1,""],UpdateRequest:[20,2,1,""]},"gino.crud.Alias":{distinct:[20,3,1,""],load:[20,3,1,""],on:[20,3,1,""]},"gino.crud.CRUDModel":{"delete":[20,4,1,""],alias:[20,3,1,""],append_where_primary_key:[20,3,1,""],create:[20,3,1,""],distinct:[20,3,1,""],get:[20,3,1,""],in_query:[20,3,1,""],load:[20,3,1,""],lookup:[20,3,1,""],none_as_none:[20,3,1,""],on:[20,3,1,""],query:[20,4,1,""],select:[20,3,1,""],to_dict:[20,3,1,""],update:[20,4,1,""]},"gino.crud.UpdateRequest":{apply:[20,3,1,""],update:[20,3,1,""]},"gino.declarative":{ColumnAttribute:[21,2,1,""],InvertDict:[21,2,1,""],Model:[21,2,1,""],declarative_base:[21,1,1,""],declared_attr:[21,1,1,""]},"gino.declarative.InvertDict":{invert_get:[21,3,1,""]},"gino.dialects":{asyncpg:[23,0,0,"-"],base:[24,0,0,"-"]},"gino.dialects.asyncpg":{AsyncEnum:[23,2,1,""],AsyncpgCompiler:[23,2,1,""],AsyncpgCursor:[23,2,1,""],AsyncpgDBAPI:[23,2,1,""],AsyncpgDialect:[23,2,1,""],AsyncpgExecutionContext:[23,2,1,""],AsyncpgIterator:[23,2,1,""],AsyncpgJSONPathType:[23,2,1,""],DBAPICursor:[23,2,1,""],GinoNullType:[23,2,1,""],NullPool:[23,2,1,""],Pool:[23,2,1,""],PreparedStatement:[23,2,1,""],Transaction:[23,2,1,""]},"gino.dialects.asyncpg.AsyncEnum":{create_async:[23,3,1,""],drop_async:[23,3,1,""]},"gino.dialects.asyncpg.AsyncpgCompiler":{bindtemplate:[23,3,1,""]},"gino.dialects.asyncpg.AsyncpgCursor":{forward:[23,3,1,""],many:[23,3,1,""],next:[23,3,1,""]},"gino.dialects.asyncpg.AsyncpgDBAPI":{Error:[23,4,1,""]},"gino.dialects.asyncpg.AsyncpgDialect":{colspecs:[23,4,1,""],cursor_cls:[23,4,1,""],dbapi_class:[23,4,1,""],driver:[23,4,1,""],execution_ctx_cls:[23,4,1,""],get_isolation_level:[23,3,1,""],has_schema:[23,3,1,""],has_sequence:[23,3,1,""],has_table:[23,3,1,""],has_type:[23,3,1,""],init_kwargs:[23,4,1,""],init_pool:[23,3,1,""],on_connect:[23,3,1,""],set_isolation_level:[23,3,1,""],statement_compiler:[23,4,1,""],supports_native_decimal:[23,4,1,""],transaction:[23,3,1,""]},"gino.dialects.asyncpg.AsyncpgJSONPathType":{bind_processor:[23,3,1,""]},"gino.dialects.asyncpg.DBAPICursor":{async_execute:[23,3,1,""],description:[23,3,1,""],get_statusmsg:[23,3,1,""],prepare:[23,3,1,""]},"gino.dialects.asyncpg.GinoNullType":{result_processor:[23,3,1,""]},"gino.dialects.asyncpg.NullPool":{acquire:[23,3,1,""],close:[23,3,1,""],raw_pool:[23,3,1,""],release:[23,3,1,""],repr:[23,3,1,""]},"gino.dialects.asyncpg.Pool":{acquire:[23,3,1,""],close:[23,3,1,""],raw_pool:[23,3,1,""],release:[23,3,1,""],repr:[23,3,1,""]},"gino.dialects.asyncpg.Transaction":{begin:[23,3,1,""],commit:[23,3,1,""],raw_transaction:[23,3,1,""],rollback:[23,3,1,""]},"gino.dialects.base":{AsyncDialectMixin:[24,2,1,""],BaseDBAPI:[24,2,1,""],Cursor:[24,2,1,""],DBAPICursor:[24,2,1,""],ExecutionContextOverride:[24,2,1,""],Pool:[24,2,1,""],PreparedStatement:[24,2,1,""],Transaction:[24,2,1,""]},"gino.dialects.base.AsyncDialectMixin":{compile:[24,3,1,""],cursor_cls:[24,4,1,""],dbapi:[24,3,1,""],dbapi_class:[24,4,1,""],init_pool:[24,3,1,""],transaction:[24,3,1,""]},"gino.dialects.base.BaseDBAPI":{Binary:[24,3,1,""],Error:[24,4,1,""],paramstyle:[24,4,1,""]},"gino.dialects.base.Cursor":{forward:[24,3,1,""],many:[24,3,1,""],next:[24,3,1,""]},"gino.dialects.base.DBAPICursor":{async_execute:[24,3,1,""],description:[24,3,1,""],execute:[24,3,1,""],executemany:[24,3,1,""],get_statusmsg:[24,3,1,""],prepare:[24,3,1,""]},"gino.dialects.base.ExecutionContextOverride":{get_result_proxy:[24,3,1,""],loader:[24,4,1,""],model:[24,4,1,""],process_rows:[24,3,1,""],return_model:[24,4,1,""],timeout:[24,4,1,""]},"gino.dialects.base.Pool":{acquire:[24,3,1,""],close:[24,3,1,""],raw_pool:[24,3,1,""],release:[24,3,1,""],repr:[24,3,1,""]},"gino.dialects.base.PreparedStatement":{all:[24,3,1,""],first:[24,3,1,""],iterate:[24,3,1,""],scalar:[24,3,1,""],status:[24,3,1,""]},"gino.dialects.base.Transaction":{begin:[24,3,1,""],commit:[24,3,1,""],raw_transaction:[24,3,1,""],rollback:[24,3,1,""]},"gino.engine":{GinoConnection:[25,2,1,""],GinoEngine:[25,2,1,""]},"gino.engine.GinoConnection":{all:[25,3,1,""],dialect:[25,3,1,""],execution_options:[25,3,1,""],first:[25,3,1,""],get_raw_connection:[25,3,1,""],iterate:[25,3,1,""],one:[25,3,1,""],one_or_none:[25,3,1,""],prepare:[25,3,1,""],raw_connection:[25,3,1,""],release:[25,3,1,""],scalar:[25,3,1,""],schema_for_object:[25,4,1,""],status:[25,3,1,""],transaction:[25,3,1,""]},"gino.engine.GinoEngine":{acquire:[25,3,1,""],all:[25,3,1,""],close:[25,3,1,""],compile:[25,3,1,""],connection_cls:[25,4,1,""],current_connection:[25,3,1,""],dialect:[25,3,1,""],first:[25,3,1,""],iterate:[25,3,1,""],one:[25,3,1,""],one_or_none:[25,3,1,""],raw_pool:[25,3,1,""],repr:[25,3,1,""],scalar:[25,3,1,""],status:[25,3,1,""],transaction:[25,3,1,""],update_execution_options:[25,3,1,""]},"gino.exceptions":{GinoException:[26,5,1,""],MultipleResultsFound:[26,5,1,""],NoResultFound:[26,5,1,""],NoSuchRowError:[26,5,1,""],UninitializedError:[26,5,1,""],UnknownJSONPropertyError:[26,5,1,""]},"gino.json_support":{ArrayProperty:[28,2,1,""],BooleanProperty:[28,2,1,""],DateTimeProperty:[28,2,1,""],IntegerProperty:[28,2,1,""],JSONProperty:[28,2,1,""],ObjectProperty:[28,2,1,""],StringProperty:[28,2,1,""]},"gino.json_support.ArrayProperty":{decode:[28,3,1,""],encode:[28,3,1,""]},"gino.json_support.BooleanProperty":{decode:[28,3,1,""],encode:[28,3,1,""],make_expression:[28,3,1,""]},"gino.json_support.DateTimeProperty":{decode:[28,3,1,""],encode:[28,3,1,""],make_expression:[28,3,1,""]},"gino.json_support.IntegerProperty":{decode:[28,3,1,""],encode:[28,3,1,""],make_expression:[28,3,1,""]},"gino.json_support.JSONProperty":{decode:[28,3,1,""],encode:[28,3,1,""],get_profile:[28,3,1,""],make_expression:[28,3,1,""],reload:[28,3,1,""],save:[28,3,1,""]},"gino.json_support.ObjectProperty":{decode:[28,3,1,""],encode:[28,3,1,""]},"gino.json_support.StringProperty":{make_expression:[28,3,1,""]},"gino.loader":{AliasLoader:[29,2,1,""],CallableLoader:[29,2,1,""],ColumnLoader:[29,2,1,""],Loader:[29,2,1,""],ModelLoader:[29,2,1,""],TupleLoader:[29,2,1,""],ValueLoader:[29,2,1,""]},"gino.loader.CallableLoader":{do_load:[29,3,1,""]},"gino.loader.ColumnLoader":{do_load:[29,3,1,""]},"gino.loader.Loader":{do_load:[29,3,1,""],get:[29,3,1,""],get_columns:[29,3,1,""],get_from:[29,3,1,""],query:[29,3,1,""]},"gino.loader.ModelLoader":{distinct:[29,3,1,""],do_load:[29,3,1,""],get_columns:[29,3,1,""],get_from:[29,3,1,""],load:[29,3,1,""],none_as_none:[29,3,1,""],on:[29,3,1,""]},"gino.loader.TupleLoader":{do_load:[29,3,1,""]},"gino.loader.ValueLoader":{do_load:[29,3,1,""]},"gino.schema":{AsyncSchemaDropper:[30,2,1,""],AsyncSchemaGenerator:[30,2,1,""],AsyncSchemaTypeMixin:[30,2,1,""],AsyncVisitor:[30,2,1,""],GinoSchemaVisitor:[30,2,1,""],patch_schema:[30,1,1,""]},"gino.schema.AsyncSchemaDropper":{visit_foreign_key_constraint:[30,3,1,""],visit_index:[30,3,1,""],visit_metadata:[30,3,1,""],visit_sequence:[30,3,1,""],visit_table:[30,3,1,""]},"gino.schema.AsyncSchemaGenerator":{visit_foreign_key_constraint:[30,3,1,""],visit_index:[30,3,1,""],visit_metadata:[30,3,1,""],visit_sequence:[30,3,1,""],visit_table:[30,3,1,""]},"gino.schema.AsyncSchemaTypeMixin":{create_async:[30,3,1,""],drop_async:[30,3,1,""]},"gino.schema.AsyncVisitor":{traverse_single:[30,3,1,""]},"gino.schema.GinoSchemaVisitor":{create:[30,3,1,""],create_all:[30,3,1,""],drop:[30,3,1,""],drop_all:[30,3,1,""]},"gino.strategies":{GinoStrategy:[31,2,1,""]},"gino.strategies.GinoStrategy":{create:[31,3,1,""],engine_cls:[31,4,1,""],name:[31,4,1,""]},"gino.transaction":{GinoTransaction:[32,2,1,""]},"gino.transaction.GinoTransaction":{commit:[32,3,1,""],connection:[32,3,1,""],raise_commit:[32,3,1,""],raise_rollback:[32,3,1,""],raw_transaction:[32,3,1,""],rollback:[32,3,1,""]},gino:{aiocontextvars:[18,0,0,"-"],api:[19,0,0,"-"],create_engine:[17,1,1,""],crud:[20,0,0,"-"],declarative:[21,0,0,"-"],dialects:[22,0,0,"-"],engine:[25,0,0,"-"],exceptions:[26,0,0,"-"],ext:[27,0,0,"-"],get_version:[17,1,1,""],json_support:[28,0,0,"-"],loader:[29,0,0,"-"],schema:[30,0,0,"-"],strategies:[31,0,0,"-"],transaction:[32,0,0,"-"]}},objnames:{"0":["py","module","Python module"],"1":["py","function","Python function"],"2":["py","class","Python class"],"3":["py","method","Python method"],"4":["py","attribute","Python attribute"],"5":["py","exception","Python exception"]},objtypes:{"0":"py:module","1":"py:function","2":"py:class","3":"py:method","4":"py:attribute","5":"py:exception"},terms:{"0x10a8ba860":12,"11th":3,"21s":40,"32c0feba61ea":40,"32c0feba61ea_add_users_t":40,"3apull_request":6,"4c59ad":37,"\u00e1d\u00e1m":[8,37],"\u4e00\u4e2a\u6c47\u7387":39,"\u4e00\u5b9a\u8981\u5168":39,"\u4e00\u65e6\u4ee3\u7801\u521d\u5177\u89c4\u6a21":39,"\u4e00\u679a":39,"\u4e00\u6837":39,"\u4e00\u79d2\u53ef\u8bfb\u767e\u4e07\u884c\u7684":39,"\u4e00\u7ad9\u5f0f\u5730\u89e3\u51b3\u4e86\u5e38\u7528":39,"\u4e09\u5e74\u540e\u7684\u4eca\u5929":39,"\u4e0a\u4e0b\u6587\u7ba1\u7406":39,"\u4e0a\u624b\u540e\u4f9d\u7136\u53ef\u4ee5\u5feb\u901f":39,"\u4e0a\u7ed9":39,"\u4e0a\u9762\u90a3\u4e2a":39,"\u4e0d\u4f1a\u53bb\u65e0\u7aef\u731c\u6d4b\u4e3b\u4eba\u7684\u610f\u56fe":39,"\u4e0d\u540c\u7684\u662f":39,"\u4e0d\u65ad\u6f14\u8fdb\u6210\u719f":39,"\u4e0d\u662f":39,"\u4e0d\u662f\u4e00\u4e2a\u4f20\u7edf\u7684":39,"\u4e0d\u6b62\u8fd9\u6837":39,"\u4e0e":39,"\u4e13\u4e1a\u7248\u5168\u5bb6\u6876":39,"\u4e13\u4e1a\u9886\u57df\u7684":39,"\u4e1a\u4f59\u65f6\u95f4\u9664\u4e86\u5f00\u53d1\u7ef4\u62a4":39,"\u4e2d\u8d1f\u8d23\u6784\u5efa":39,"\u4e3a":39,"\u4e3a\u4e86\u8ba9\u4e0d\u540c\u5e94\u7528\u573a\u666f\u4e0b\u7684\u7528\u6237\u4f53\u9a8c\u5230\u6700\u5927\u7684\u5584\u610f":39,"\u4e3a\u4e86\u9e21\u6bdb\u849c\u76ae\u7684\u5c0f\u4e8b\u5927\u52a8\u5e72\u6208":39,"\u4e3a\u4ec0\u4e48\u8fd9\u4e48\u773c\u719f":39,"\u4e3b\u8981\u8bf4\u7684\u662f\u5f00\u53d1\u6548\u7387":39,"\u4e4b\u7985\u5b8c\u7f8e\u8868\u8fbe\u4e86":39,"\u4e5f\u53ef\u4ee5\u7528":39,"\u4e5f\u63d0\u4f9b\u4e86\u5bf9\u8c61\u6620\u5c04\u7684\u5de5\u5177":39,"\u4e5f\u662f":39,"\u4e5f\u66fe\u5728\u521b\u4e1a\u7684\u6f6e\u6d41\u4e2d\u7559\u4e0b\u8eab\u5f71":39,"\u4e5f\u6709\u4e00\u5957\u7cbe\u5999\u7684\u663e\u5f0f\u673a\u5236":39,"\u4e86\u89e3\u4e00\u4e0b":39,"\u4e8c\u5341\u4e94\u516d\u5e74\u7684\u7f16\u7a0b\u53f2\u548c\u5341\u4e09\u56db\u5e74\u7684\u5de5\u4f5c\u7ecf\u9a8c\u6559\u4f1a\u4e86\u6211\u8bb8\u591a\u8f6f\u4ef6\u5f00\u53d1\u7684\u5965\u4e49":39,"\u4e92\u91d1":39,"\u4eb2\u8eab\u7ecf\u5386\u5e76\u89c1\u8bc1\u4e86\u8f6f\u4ef6\u6280\u672f\u968f\u7740\u624b\u6e38":39,"\u4ec0\u4e48\u7684\u90fd\u6709":39,"\u4ece\u4e0a\u624b\u6559\u7a0b\u5230\u539f\u7406\u8bf4\u660e\u5e94\u6709\u5c3d\u6709":39,"\u4ece\u6bd4\u8f83\u65e9\u5c31\u89e3\u8026\u4e86\u4e0d\u540c":39,"\u4ece\u7b80\u5355\u793a\u8303\u5230\u751f\u4ea7\u73af\u5883\u7684\u5404\u79cd\u4f8b\u5b50\u54c1\u79cd\u9f50\u5168":39,"\u4ee5\u4e0b\u662f\u8fd1\u6765\u7edf\u8ba1\u5230\u7684\u5173\u4e8e":39,"\u4ee5\u53ca":39,"\u4ee5\u53ca\u4e0b\u9762\u8fd9\u4e9b\u4e00\u76f4\u9700\u8981\u7684\u5e2e\u52a9":39,"\u4ee5\u53ca\u4e2d\u6587":39,"\u4ee5\u540c\u65f6\u83b7\u53d6\u6240\u6709\u7684\u4e66\u548c\u4ed6\u4eec\u7684\u4f5c\u8005":39,"\u4ee5\u8282\u7701\u5b66\u4e60\u548c\u8fc1\u79fb\u6210\u672c":39,"\u4f18\u52bf\u4e0e\u4e0d\u8db3":38,"\u4f20\u7edf":39,"\u4f46":39,"\u4f46\u4e0d\u662f\u4e00\u4e2a\u4f20\u7edf\u7684":39,"\u4f46\u5e94\u7528\u5230\u5927\u578b\u9879\u76ee\u4e2d\u5374\u5341\u5206\u8003\u9a8c\u5f00\u53d1\u4eba\u5458\u7684\u5e73\u5747\u6c34\u5e73":39,"\u4f46\u662f\u5bf9\u4e8e\u66f4\u590d\u6742\u7684\u67e5\u8be2":39,"\u4f46\u6ca1\u5f81\u5f97\u540c\u610f\u5c31\u4e0d\u8d34\u51fa\u6765\u4e86":39,"\u4f46\u90fd\u662f\u540c\u884c\u5c31\u4e0d\u591a\u8bc4\u4ef7\u4e86":39,"\u4f60\u4e00\u5b9a\u4f1a\u6709\u611f\u77e5\u7684":39,"\u4f60\u53ef\u4ee5\u7528":39,"\u4f60\u751a\u81f3\u53ef\u4ee5\u624b\u5199\u4efb\u4f55":39,"\u4f60\u80af\u5b9a\u8981\u95ee\u4e00\u53e5":39,"\u4f8b\u5982\u524d\u9762\u7684":39,"\u4fc4\u6587\u7684\u7ffb\u8bd1":39,"\u4fc4\u8bed\u6559\u7a0b":39,"\u4fee":39,"\u501f\u9274\u4e86":39,"\u505a\u529f\u80fd":39,"\u5143":39,"\u5148\u8bf4":38,"\u5168\u90fd\u517c\u5bb9":39,"\u5173\u4e8e\u4f5c\u8005":38,"\u5176\u4e2d":39,"\u518d\u52a0\u4e0a":39,"\u518d\u8bf4":38,"\u5199":39,"\u51fa\u54c1\u5fc5\u5c5e\u7cbe\u54c1\u7684":39,"\u51fa\u54c1\u65b9\u662f":39,"\u51fa\u95ee\u9898\u627e\u4e0d\u5230\u539f\u56e0":39,"\u5219\u4f1a\u5c06\u8fd9\u4e9b\u53d8\u66f4\u5e94\u7528\u5230\u6570\u636e\u5e93\u91cc":39,"\u5219\u662f":39,"\u521b\u9020\u51fa\u4e86\u4e00\u79cd\u7206\u70b8\u5f0f\u7684\u5316\u5b66\u53cd\u5e94":39,"\u52a0\u4e00\u9897\u661f\u661f":39,"\u52a0\u8f7d\u5668\u4e0e\u5173\u7cfb":39,"\u52a0\u8f7d\u5668\u7684\u7528\u6cd5\u4e5f\u662f\u5f88\u7b80\u5355\u7684":39,"\u5341\u5206\u5feb\u6377":39,"\u5343\u661f\u9879\u76ee":39,"\u5373\u5173\u7cfb\u5bf9\u8c61\u6620\u5c04":39,"\u5373\u88c5\u5373\u7528":39,"\u539f\u6559\u65e8\u4e3b\u4e49\u8005":39,"\u53bb":39,"\u53c2\u4e0e\u8ba8\u8bba":39,"\u53c2\u8003\u6587\u732e":38,"\u53c8\u7b80\u5355\u660e\u4e86\u5730\u8bbf\u95ee\u6570\u636e\u5e93\u5462":39,"\u53cd\u566c\u7684\u60c5\u666f":39,"\u53e6\u4e00\u65b9\u9762":39,"\u53e6\u5916":39,"\u53ea\u613f\u5b9a\u4e49":39,"\u53ea\u6709\u5f02\u6b65\u6267\u884c\u65f6\u624d\u7528\u5230":39,"\u53ef\u4ee5\u76f4\u63a5\u83b7\u53d6\u5230":39,"\u53ef\u4ee5\u8c28\u614e\u5730\u7528\u4e8e\u751f\u4ea7\u73af\u5883\u4e86":39,"\u53ef\u5b9a\u5236\u5316\u7684\u52a0\u8f7d\u5668":39,"\u53ef\u9009":39,"\u5404\u4e2a":39,"\u5404\u5927\u6d41\u884c\u5f02\u6b65":39,"\u5404\u79cd":39,"\u540c\u65f6":39,"\u540c\u65f6\u4e5f\u4e0d\u9700\u8981\u4e3a\u8fd9\u79cd\u660e\u786e\u6027\u4ed8\u51fa\u8fc7\u5927\u7684\u5de5\u7a0b\u4ee3\u4ef7":39,"\u5462":39,"\u548c":39,"\u54a6":39,"\u54e6\u4e0d":39,"\u56de\u7b54\u95ee\u9898":39,"\u56e0\u4e3a\u7269\u6781\u5fc5\u53cd":39,"\u56e0\u6b64":39,"\u56e0\u6b64\u8fd8\u4e0d\u80fd\u5b8c\u5168\u53d1\u6325":39,"\u5728\u5e26\u6765\u751f\u6d3b\u4fbf\u5229\u7684\u540c\u65f6":39,"\u5728\u6267\u884c\u6548\u7387\u4e0a\u4e5f\u6ca1\u843d\u4e0b":39,"\u5728\u7ebf\u6e38\u620f\u7b49\u9ad8\u5e76\u53d1\u9886\u57df":39,"\u5728\u8fd9\u4e2a\u70e7\u8111\u7684\u5f02\u6b65\u4e16\u754c\u91cc":39,"\u5728\u8fd9\u91cc\u5c31\u4e0d\u4e00\u4e00\u5217\u4e3e\u4e86":39,"\u57fa\u4e8e":39,"\u57fa\u7840\u6559\u7a0b":39,"\u586b\u8865\u4e86\u56fd\u5185\u5916":39,"\u589e\u5220\u6539\u67e5":39,"\u5927":39,"\u5927\u5b66\u91cc\u5f00\u59cb\u5199":39,"\u5927\u91cf\u7684\u6210\u529f\u6848\u4f8b\u4e5f\u8bc1\u660e\u4e86":39,"\u5929\u751f\u538c\u6076":39,"\u5982\u679c\u50cf\u8fd9\u6837":39,"\u5988\u5988\u518d\u4e5f\u4e0d\u7528\u62c5\u5fc3\u6211\u4e0d\u4f1a\u96c6\u6210":39,"\u5b83\u4eec":39,"\u5b83\u4eec\u5173\u6ce8\u7684\u91cd\u70b9\u4e0e":39,"\u5b83\u7684\u5168\u79f0\u662f":39,"\u5b83\u7684\u5b9e\u4f8b":39,"\u5b98\u5ba3":38,"\u5b9a\u4e0b\u4e86\u4e24\u4e2a\u4e1a\u7ee9\u76ee\u6807":39,"\u5b9e\u4f8b":39,"\u5b9e\u4f8b\u7684":39,"\u5b9e\u4f8b\u8bbe\u7f6e\u5230":39,"\u5bf9":39,"\u5bf9\u4e8e\u4e0a\u4e86\u89c4\u6a21\u7684\u5f02\u6b65\u5de5\u7a0b\u9879\u76ee\u6765\u8bf4\u5c24\u4e3a\u91cd\u8981":39,"\u5bf9\u4e8e\u5982\u4f55\u5c06\u6570\u636e\u5e93\u67e5\u8be2\u7ed3\u679c\u7ec4\u88c5\u6210\u5185\u5b58\u5bf9\u8c61\u53ca\u5176\u5c5e\u6027":39,"\u5bf9\u4e8e\u7b80\u5355\u76f4\u89c2\u7684\u4e00\u5bf9\u4e00\u52a0\u8f7d":39,"\u5bf9\u5176\u6267\u884c":39,"\u5bf9\u8c61":39,"\u5bf9\u8c61\u5173\u7cfb\u6620\u5c04":39,"\u5c06\u6570\u636e\u5e93\u8fd4\u56de\u7ed3\u679c\u7684\u6bcf\u4e00\u884c\u4e2d":39,"\u5c0f\u65f6\u5019\u5199":39,"\u5c31\u53d8\u6210\u4e86\u4eba\u540d":39,"\u5c31\u5b9e\u73b0\u4e86":39,"\u5c31\u662f\u4ed6\u4eec\u7684\u4f5c\u54c1":39,"\u5c31\u662f\u5185\u5b58\u91cc\u9762\u7684\u5e38\u89c4\u5bf9\u8c61":39,"\u5c31\u662f\u660e\u786e\u6027\u7684\u5173\u952e":39,"\u5c31\u662f\u6709\u4eba\u53d7\u4e0d\u4e86\u4e86\u81ea\u5df1\u5199\u4e86\u4e00\u4e2a\u7c7b\u578b\u6ce8\u89e3":39,"\u5c31\u6ca1\u6709\u6570\u636e\u5e93\u64cd\u4f5c":39,"\u5c5e\u4e8e":39,"\u5c5e\u6027\u4e0a":39,"\u5c81\u5f00\u59cb\u63a5\u89e6\u7f16\u7a0b":39,"\u5de5\u4f5c\u5934\u4e94\u5e74\u8f6c\u5411\u4e86":39,"\u5df2\u7ecf\u521d\u6b65\u5177\u5907\u53d1\u5e03":39,"\u5e74\u521b\u4f5c\u4e4b\u521d":39,"\u5e74\u751f\u4eba":39,"\u5e76\u4e0d\u662f\u4ece\u5934\u9020\u8f6e\u5b50":39,"\u5e76\u63a5\u89e6\u5230\u4e86":39,"\u5efa\u8bbe\u793e\u4f1a\u4e3b\u4e49":38,"\u5f00\u53d1\u4eba\u5458\u7684\u65f6\u95f4\u786e\u5b9e\u6bd4\u673a\u5668\u7684\u65f6\u95f4\u503c\u94b1":39,"\u5f00\u53d1\u5e94\u7528\u7a0b\u5e8f\u7684\u65f6\u5019\u4e0d\u7528\u62c5\u5fc3\u4f1a\u88ab\u610f\u6599\u4e4b\u5916\u7684\u884c\u4e3a\u6240\u60ca\u5413\u5230":39,"\u5f00\u6e90\u793e\u533a\u91cc\u4e5f\u76f8\u7ee7\u51fa\u73b0\u4e86\u50cf":39,"\u5f00\u7bb1\u5373\u7528\u7684\u6570\u636e\u5e93\u53d8\u66f4\u7ba1\u7406\u5de5\u5177":39,"\u5f02\u6b65":39,"\u5f02\u6b65\u7f16\u7a0b\u518d\u6dfb\u4e00\u5229\u5668":38,"\u5f02\u6b65\u7f16\u7a0b\u8fd9\u4e2a\u8bdd\u9898\u4e5f\u5728\u9010\u6e10\u5347\u6e29":39,"\u5f15\u64ce":39,"\u5f15\u64ce\u4e0e\u8fde\u63a5":39,"\u5f62\u4f3c\u800c\u795e\u4e0d\u4f3c":39,"\u5f80\u5f80\u4f1a\u9009\u62e9\u727a\u7272\u660e\u786e\u6027":39,"\u5f88\u7b80\u5355\u7684\u4e00\u4e2a\u5916\u8fde\u63a5\u67e5\u8be2":39,"\u5f97\u5929\u72ec\u539a\u7684\u7075\u6d3b\u6027":39,"\u5feb\u4e50\u5730\u7f16\u7a0b":39,"\u5feb\u6377\u65b9\u5f0f":39,"\u6027\u80fd\u83ab\u540d\u5176\u5999\u7684\u5dee":39,"\u610f\u5473\u7740\u6211\u4eec\u8981\u8df3\u51fa\u53bb\u6267\u884c\u6570\u636e\u5e93\u64cd\u4f5c\u4e86":39,"\u6210\u529f\u5b9e\u73b0\u4e86\u5bf9\u540c\u671f\u7ade\u54c1":39,"\u6211\u5c31\u7ed9":39,"\u6211\u771f":39,"\u6211\u7d22\u6027\u5728":39,"\u6216\u8005\u7528":39,"\u6240\u4ee5":39,"\u6240\u4ee5\u5728":39,"\u6240\u4ee5\u6b22\u8fce\u5927\u5bb6\u4e00\u8d77\u6765\u5efa\u8bbe":39,"\u6240\u4ee5\u8fd9\u4e9b\u529f\u80fd\u4f1a\u9646\u7eed\u5728":39,"\u6240\u6709\u4eba":39,"\u6240\u6709\u8fd9\u4e9b\u95ee\u9898\u5982\u679c\u518d\u653e\u8fdb\u5f02\u6b65\u7f16\u7a0b\u7684\u73af\u5883\u91cc":39,"\u624b\u6cd5":39,"\u6267\u884c":39,"\u627e":39,"\u6307\u54ea\u513f\u6253\u54ea\u513f":39,"\u6362\u53e5\u8bdd\u8bf4":39,"\u63d0":39,"\u63d0\u5347\u4e86\u5199\u4ee3\u7801\u7684\u5e78\u798f\u6307\u6570":39,"\u63d0\u5efa\u8bae":39,"\u6570\u636e\u5e93\u4e8b\u52a1":39,"\u6570\u636e\u5e93\u4e8b\u52a1\u5c01\u88c5\u548c\u5d4c\u5957":39,"\u6587\u5a31":39,"\u65b0\u5a92\u4f53":39,"\u65b9\u4fbf\u5feb\u6377":38,"\u65b9\u8a00\u548c\u9a71\u52a8\u7684\u96c6\u6210":39,"\u65e0\u989d\u5916\u4f9d\u8d56\u5173\u7cfb":39,"\u65e2\u7b80\u5355\u53c8\u660e\u4e86\u6709\u6ca1\u6709":39,"\u660e\u786e\u6027":39,"\u662f":39,"\u662f\u4e00\u4e2a":39,"\u662f\u4e00\u4e2a\u5f00\u6e90\u9879\u76ee":39,"\u662f\u4e00\u7c7b\u5f00\u53d1\u4eba\u5458\u559c\u95fb\u4e50\u89c1\u7684\u6548\u7387\u5de5\u5177":39,"\u662f\u4e0d\u662f\u5341\u5206\u65b9\u4fbf":39,"\u662f\u5b8c\u5168\u65e0\u72b6\u6001\u7684\u666e\u901a":39,"\u662f\u7528\u6765\u8bbf\u95ee\u6570\u636e\u5e93\u7684":39,"\u662f\u7684":39,"\u662f\u8c01":38,"\u66f4\u591a\u7684\u4f8b\u5b50\u548c\u6587\u6863":39,"\u66f4\u91cd\u8981\u7684\u662f\u5e26\u6765\u4e86\u6574\u4e2a":39,"\u6700\u540e":39,"\u6700\u540e\u4e5f\u662f\u6700\u91cd\u8981\u7684":39,"\u6700\u540e\u5c06":39,"\u6700\u5927\u7a0b\u5ea6\u7684\u4fbf\u5229":39,"\u6700\u5c11\u4fb5\u5165\u578b":39,"\u6709\u6ca1\u6709\u529e\u6cd5\u53ef\u4ee5\u65e2\u65b9\u4fbf\u5feb\u6377":39,"\u670d\u52a1":39,"\u671f\u95f4\u8d21\u732e\u4e86":39,"\u6765\u4fee\u6539\u5c5e\u6027":39,"\u6765\u521b\u5efa\u65b0\u7684\u5b9e\u4f8b":39,"\u6765\u6362\u53d6\u4fbf\u6377\u6027":39,"\u6781\u5927\u5730":39,"\u67d0\u4e9b\u573a\u666f\u4e0b":39,"\u6846\u67b6":39,"\u6846\u67b6\u4e86":39,"\u6846\u67b6\u63d2\u4ef6\u7684\u7ef4\u62a4\u5de5\u4f5c\u9700\u8981\u591a\u4eba\u8ba4\u9886":39,"\u6846\u67b6\u6765\u8bf4\u662f\u4e0d\u53ef\u63a5\u53d7\u7684":39,"\u6846\u67b6\u7684\u5b9a\u5236\u7248\u63d2\u4ef6":39,"\u6b22\u8fce\u6765\u5230":39,"\u6b63\u72b9\u5982":39,"\u6bd4\u5982\u4e00\u4e2a\u7528\u6237\u53ef\u80fd\u5199\u4e86\u5f88\u591a\u672c\u4e66":39,"\u6bd4\u5982\u6267\u884c":39,"\u6bd4\u5982\u6ca1\u6709\u7167\u987e\u5230":39,"\u6bd4\u5982\u7528":39,"\u6bd4\u5982\u8bf4":39,"\u6c7d\u8f66\u7b49\u884c\u4e1a\u7684\u8d77\u8d77\u4f0f\u4f0f":39,"\u6ca1\u6709":39,"\u6ca1\u6709\u53d1\u7968":39,"\u6ca1\u6709\u9519":39,"\u6df1\u53d7\u4fc4\u7f57\u65af\u548c\u4e4c\u514b\u5170\u4eba\u6c11\u7684\u7231\u6234":39,"\u706b\u529b\u5168\u5f00\u578b":39,"\u7136\u540e\u5b9a\u5236\u52a0\u8f7d\u5668\u81ea\u52a8\u52a0\u8f7d\u6210\u671f\u671b\u7684\u5bf9\u8c61\u5173\u7cfb":39,"\u7136\u540e\u5c06\u8be5\u884c\u4e2d\u5269\u4e0b\u7684\u5c5e\u4e8e":39,"\u7136\u540e\u8fd9\u6837\u6765\u52a0\u8f7d\u8fd9\u79cd\u591a\u5bf9\u4e00\u5173\u7cfb":39,"\u7248\u672c\u4e2d\u8ddf\u4e0a":39,"\u7279\u522b\u611f\u8c22":39,"\u751f\u957f\u7684\u6e29\u5e8a":39,"\u7528":39,"\u7528\u6237\u5305":39,"\u7535\u5546":39,"\u7684":39,"\u7684\u540c\u5b66\u6765\u8bf4\u53ef\u80fd\u5e76\u4e0d\u964c\u751f":39,"\u7684\u57fa\u7840\u4e0a\u5f00\u53d1\u7684":39,"\u7684\u589e\u5f3a\u63d2\u4ef6":39,"\u7684\u590d\u6742\u5ea6\u4e86":39,"\u7684\u5b57\u6bb5\u52a0\u8f7d\u6210\u4e00\u4e2a":39,"\u7684\u5b66\u4e60\u66f2\u7ebf\u524d\u5e73\u540e\u9661":39,"\u7684\u5b9a\u4e49\u98ce\u683c":39,"\u7684\u5e94\u7528\u6848\u4f8b":39,"\u7684\u5e95\u5c42\u6838\u5fc3":39,"\u7684\u5f3a\u529b\u52a0\u6301":39,"\u7684\u5f88\u591a\u8bbe\u8ba1\u90fd\u53d7\u5230\u4e86\u660e\u786e\u6027\u7684\u5f71\u54cd":39,"\u7684\u652f\u6301":39,"\u7684\u6587\u6863":39,"\u7684\u6700\u5927\u4f18\u52bf\u8fd8\u662f\u5728\u4e8e\u5145\u5206\u5e73\u8861\u4e86\u5f00\u53d1\u6548\u7387\u548c\u660e\u786e\u6027\u4e4b\u95f4\u7684\u8fa9\u8bc1\u77db\u76fe\u5173\u7cfb":39,"\u7684\u6f5c\u80fd":39,"\u7684\u751f\u6001\u73af\u5883":39,"\u7684\u7528\u6237\u5bf9\u8c61":39,"\u7684\u7acb\u573a":39,"\u7684\u7c7b\u578b\u63d0\u793a":39,"\u7684\u8d21\u732e":39,"\u7684\u9012\u5f52\u5b9a\u4e49":39,"\u7684\u964d\u7ef4\u6253\u51fb":39,"\u76ee\u524d\u4e5f\u662f\u4e0d\u652f\u6301\u7684":39,"\u76ee\u524d\u5728\u829d\u5927\u7ee7\u7eed\u505a\u751f\u7269\u5927\u6570\u636e\u76f8\u5173\u7684\u5f00\u6e90\u9879\u76ee":39,"\u76ee\u524d\u6025\u9700\u5e2e\u52a9\u7684\u6709":39,"\u76ee\u524d\u652f\u6301\u4e09\u79cd\u4e0d\u540c\u7a0b\u5ea6\u7684\u7528\u6cd5":39,"\u76ee\u524d\u7684\u4e0d\u8db3\u4e4b\u5904\u8fd8\u6709\u4e00\u4e9b":39,"\u77ff\u5708":39,"\u793e\u4ea4":39,"\u7a0d\u6709\u4e0d\u540c":39,"\u7a33\u5b9a\u7248\u53d1\u5e03\u7684\u524d\u5915\u505a\u4e2a\u5e74\u7ec8\u603b\u7ed3":39,"\u7a33\u5b9a\u7248\u7684\u5404\u79cd\u6761\u4ef6":39,"\u7a7a\u624b\u63a5":39,"\u7b14\u8005\u5de5\u4f5c\u4e0a\u5f00\u53d1\u7684\u4e00\u4e2a\u670d\u52a1":39,"\u7b49":39,"\u7b49\u4f18\u79c0\u7684\u5f02\u6b65":39,"\u7b49\u5230\u9700\u8981\u64cd\u4f5c\u6570\u636e\u5e93\u7684\u65f6\u5019":39,"\u7b49\u591a\u9879\u4fbf\u6377\u529f\u80fd":39,"\u7b49\u5f00\u6e90\u9879\u76ee\u4e14\u4e00\u53d1\u4e0d\u53ef\u6536\u62fe":39,"\u7b49\u6846\u67b6\u7684\u9646\u7eed\u6d8c\u73b0":39,"\u7b49\u9879\u76ee\u4e86\u89e3\u4e86\u5f02\u6b65\u7f16\u7a0b":39,"\u7b80\u5355\u660e\u4e86":38,"\u7c7b":39,"\u7c7b\u4f3c":39,"\u7cbe\u51c6\u63a7\u5236\u52a0\u8f7d\u884c\u4e3a":39,"\u7ec8\u8eab\u4e0d\u5a5a\u578b":39,"\u7edd\u4e0d\u662f\u9ed1\u54c8":39,"\u7edd\u5bf9\u7eff\u8272\u73af\u4fdd\u65e0\u6bd2\u526f\u4f5c\u7528":39,"\u7ef4\u57fa\u767e\u79d1":39,"\u7ef4\u62a4\u793e\u533a":39,"\u800c":39,"\u800c\u5168\u6743\u4ea4\u7ed9\u7528\u6237\u6765\u660e\u786e\u5730\u5b9a\u4e49":39,"\u800c\u662f\u5728":39,"\u804a\u5929\u673a\u5668\u4eba":39,"\u80fd\u53eb\u4e0a\u540d\u5b57\u7684\u50cf":39,"\u80fd\u5728\u5feb\u901f\u539f\u578b\u5f00\u53d1\u4e2d\u5927\u5c55\u8eab\u624b":39,"\u81ea\u7136\u662f\u4f3a\u5019\u5230\u5bb6\u7684":39,"\u867d\u7136\u6587\u6863\u8fd8\u5728\u52aa\u529b\u7f16\u5199\u4e2d":39,"\u867d\u7136\u662f":39,"\u8868":39,"\u8868\u7ed3\u6784\u5b9a\u4e49":39,"\u88ab\u5e7f\u6cdb\u5e94\u7528\u4e8e\u8bf8\u5982\u5b9e\u65f6\u6c47\u7387":39,"\u8981\u7528":39,"\u8bbf\u95ee\u5c5e\u6027":39,"\u8dd1\u8d77\u6765\u4e5f\u662f\u53ef\u4ee5\u98de\u5feb\u7684":39,"\u8f7b\u91cf\u7ea7":39,"\u8fc1\u79fb":39,"\u8fd8\u4f1a\u5076\u5c14\u4fee\u4e00\u4fee":39,"\u8fd8\u4f1a\u8fd4\u56de\u4e00\u4e2a\u5305\u542b\u672c\u6b21\u53d8\u66f4\u7684\u4e2d\u95f4\u7ed3\u679c":39,"\u8fd8\u63d0\u4f9b\u4e86":39,"\u8fd8\u662f\u7b14\u8005\u81ea\u5df1\u5199\u7684\u4e00\u4e2a\u5de5\u5177":39,"\u8fd8\u6709\u51e0\u4e2a\u5546\u7528\u7684":39,"\u8fd8\u6709\u5f88\u591a\u7c7b\u4f3c\u7684\u7279\u6027":39,"\u8fd8\u8d34\u5fc3\u5730\u63d0\u4f9b\u4e86\u4e2d\u6587\u6587\u6863":39,"\u8fd9\u4e2a\u9879\u76ee\u5c31\u53eb":39,"\u8fd9\u4e48\u505a\u9664\u4e86\u80fd\u4fdd\u6301\u719f\u6089\u7684\u5473\u9053":39,"\u8fd9\u4e48\u5b9a\u4e49\u8868\u7ed3\u6784\u751a\u81f3\u8ba9\u4eba\u6709\u70b9\u5c0f\u5174\u594b":39,"\u8fd9\u4e9b\u64cd\u4f5c\u90fd\u4e0d\u4f1a\u8bbf\u95ee\u6570\u636e\u5e93":39,"\u8fd9\u4ee3\u7801\u4f60\u8ba9\u6211\u600e\u4e48\u8c03\u8bd5":39,"\u8fd9\u5bf9\u4e8e\u4e00\u6b3e\u4f18\u79c0\u7684\u5f02\u6b65":39,"\u8fd9\u5c31\u662f":39,"\u8fd9\u662f\u8c01":39,"\u8fd9\u91cc\u7684":39,"\u8fde\u63a5\u6c60\u7ba1\u7406\u548c\u61d2\u52a0\u8f7d":39,"\u901a\u8fc7":39,"\u90a3\u4e3a\u4ec0\u4e48\u975e\u8bf4":39,"\u90a3\u5c31\u662f":39,"\u90e8":39,"\u90fd\u662f\u53ea\u5728\u5185\u5b58\u91cc\u4fee\u6539\u5bf9\u8c61\u7684\u5c5e\u6027":39,"\u90fd\u6709\u53ef\u80fd\u89e6\u53d1\u4e00\u5927\u5806\u610f\u60f3\u4e0d\u5230\u7684\u6570\u636e\u5e93\u8c03\u7528":39,"\u914d\u5408\u4e00\u4e2a\u76f4\u89c2\u7684\u52a0\u8f7d\u5668":39,"\u91cc\u7684\u5bf9\u8c61\u6620\u5c04\u4e0d\u80fd\u4e22":39,"\u91cd\u89c6\u5f00\u53d1\u6548\u7387\u7684\u6982\u5ff5\u5bf9\u4e8e\u5199":39,"\u957f\u671f\u6d3b\u8dc3\u7684\u8d21\u732e\u8005\u8fd8\u80fd\u83b7\u8d60\u4ef7\u503c":39,"\u968f\u4fbf\u4e00\u53e5":39,"\u968f\u7740":39,"\u968f\u7740\u8fd9\u51e0\u5e74":39,"\u975e\u5178\u578b\u5f02\u6b65":39,"\u9879\u76ee\u5916":39,"\u9879\u76ee\u6216\u591a\u6216\u5c11\u90fd\u4f1a\u9047\u5230":39,"\u9879\u76ee\u7684\u8d21\u732e":39,"\u9886\u57df\u7684\u7a7a\u767d":39,"\u9ad8\u6027\u80fd\u6a21\u677f\u9879\u76ee":39,"abstract":[3,21,29,37],"boolean":[9,25,29],"break":[1,13,37,40],"case":[2,3,5,8,10,11,12,13,19,37],"class":[2,5,8,9,10,11,12,19,20,21,23,24,25,28,29,30,31,32,34,37,39,40,41],"default":[2,3,5,6,9,10,11,12,13,19,20,21,23,25,28,29,34,35,37,40,41],"enum":[23,37],"export":[5,6],"final":[1,2,3,8,25,37,40,41],"float":9,"function":[2,6,9,18,23,25,29,40],"ila\u00ef":37,"import":[1,2,3,5,8,9,10,11,12,18,19,21,27,29,31,34,35,37,39,40,41],"int":[9,13,34,40],"long":[1,2,3,13,25,34,35],"micha\u0142":37,"new":[1,2,3,5,6,8,10,12,19,20,21,25,29,31,34,37,38,41],"null":[2,37],"public":12,"ram\u00edrez":39,"return":[1,2,3,8,9,10,12,13,19,20,21,23,25,29,31,34,35,37,40,41],"sebasti\u00e1n":39,"short":[2,3,12],"static":[24,40],"super":[3,10],"switch":[1,2,19,37],"transient":2,"true":[2,3,5,8,9,10,12,13,19,20,21,23,24,25,29,30,34,35,39,40,41],"try":[1,2,3,8,13,25,32,37,40,41],"var":6,"while":[1,2,3,8,10,12,19,20,25,32,37,41],"za\u0165ko":37,Added:37,And:[1,2,5,6,9,10,20,37,40,41],Being:3,But:[1,2,3,10,40],Doing:3,For:[1,2,3,6,8,10,12,19,20,25,29,32,37,40,41],IDE:39,IDs:10,INTO:[13,41],NOT:[10,21],Not:[8,14,21,29,39,41],One:[1,4,5,25],PRs:40,That:[1,2,3,5,10,13,34,40,41],The:[0,2,3,6,8,9,10,11,12,13,19,20,21,23,25,29,32,34,35,37,39,40,41],Their:21,Then:[2,3,6,10,12,25,40,41],There:[1,2,3,11,12,25,37,41],These:[3,37],Use:[4,8,20,41],Used:[21,37],Using:[8,9,10,34],WITH:6,Will:40,With:[1,2,3,10,20,40,41],Yes:2,__all__:37,__attr_factory__:21,__init__:[10,40],__main__:34,__metadata__:21,__model__:37,__name__:[21,34,40],__repr__:34,__table__:[12,20,21],__table_args__:[21,37,41],__tablename__:[5,8,9,10,12,21,34,37,39,40,41],__values__:21,_base:23,_bind:8,_child:10,_children:10,_engin:23,_event:23,_idx1:41,_idx2:41,_is_metadata_oper:30,_name_idx:8,_parent:10,_pk:41,_schematranslatemap:25,_test:40,_update_request_cl:37,abandon:37,abcd:6,abil:[10,37],abl:[3,40],abnormal_detect:9,abort:34,about:[1,2,3,5,6,8,12,13,20,25,37,41],abov:[1,2,3,8,10,29,40,41],absolut:[2,3],accept:[2,19,20,23,25,37,41],access:[0,2,8,12,13,21,25,32,34,37,40,41],access_log:9,accid:2,accord:[3,25,29,35],achiev:[1,8,10,12,19,25],acquir:[2,3,12,19,23,24,25,32,34,37],acquisit:3,across:[29,40],act:[1,2,41],action:[6,32],activ:[6,25,40],actual:[1,2,3,10,12,13,20,21,25,34,40,41],adapt:41,add:[1,2,3,5,6,8,10,19,20,27,37,38,41],add_child:10,add_us:40,added:[19,21,25,40,41],addit:[1,2,9,10,29],addition:[3,20],address:[5,12],adjac:8,adjust:40,admin:4,adopt:37,advanc:4,advic:3,affect:[20,37,41],after:[1,2,3,5,12,13,19,20,23,25,29,34,37,40,41],after_get:9,afterward:23,again:[1,2,3,8,10,25,40,41],against:6,age:[9,20,32],age_idx:9,aggreg:20,aintq:39,aiocontextvar:[2,4,15,16,17,37,39],aiohttp:[37,39],alemb:[4,9,12,19,38,39,41],alembic_sampl:5,ali:8,alia:[8,10,19,20,23,24,25,29,31,37],aliasload:29,alik:37,all:[1,2,3,5,6,8,9,10,12,13,19,20,21,24,25,29,32,34,35,37,40,41],all_us:41,allow:[1,2,12,19,21,23,37,40,41],alon:2,alpha:[8,37],alpin:[6,40],alreadi:[1,3,10,21,41],alright:1,also:[1,2,3,5,8,10,12,13,19,20,21,23,25,27,29,37,40,41],altern:[2,8,11,25,40,41],although:10,alwai:[2,5,6,8,12,19,20,25,29,32,34,37,40,41],amaz:[8,41],amount:2,analysi:40,andrei:39,ani:[1,2,3,5,6,8,19,21,23,25,27,29,37],anoth:[1,2,3,10,20,25,29,41],answer:[1,8],anyth:[3,6,12,25,37],api:[2,3,8,12,15,17,23,25,32,38,39,41],apirout:40,apk:40,app:[3,8,11,34,35,37,40],appear:1,append:20,append_where_primary_kei:20,appli:[2,4,12,20,25,32,39,40,41],applic:[3,8,19,35,37,40,41],appreci:6,approach:[1,3,8],arbitrari:3,archlinux:39,arg:[17,19,20,21,23,24,25,30,32],argument:[2,8,10,19,20,23,25,29,31,35,37,41],around:[25,39],arq:39,arrai:[9,23,37],arrayproperti:[9,28],arriv:1,arrrrh:1,articl:6,artifact:40,asap:1,ascend:10,ascii_lett:[8,10],asgi:40,ask:[2,4],assembl:[2,10],assert:[13,21,32,37,40,41],assertionerror:37,assign:2,assist:10,associ:[2,12],assum:[1,3,40],assumpt:32,async:[1,2,3,8,10,12,13,19,20,23,24,25,30,31,32,34,37,39,40,41],async_execut:[23,24],asyncdialectmixin:[23,24],asyncenum:23,asynchron:[0,2,10,12,13,14,19,25,32,41],asyncio:[0,1,2,4,10,12,14,18,39,41],asyncpg:[2,3,8,11,12,13,14,15,16,17,22,25,31,35,37,39,40,41],asyncpg_deleg:37,asyncpgcompil:23,asyncpgcursor:23,asyncpgdbapi:23,asyncpgdialect:23,asyncpgexecutioncontext:23,asyncpgiter:23,asyncpgjsonpathtyp:23,asyncpgsa:[12,39],asyncschemadropp:30,asyncschemagener:30,asyncschematypemixin:30,asyncvisitor:30,ath:20,atom:20,attack:40,attent:34,attribut:[8,10,12,20,21,25,29,37,41],attributeerror:19,audienc:41,audit_profil:9,aur:39,austin:8,authent:3,author:[3,19,39,40],author_id:39,auto:[9,20,21,40],autocommit:3,autogener:[5,40],autom:[10,40],automat:[10,18,20,21,25,29,31,32,34,40],avail:[2,8,12,13,20,21,25,32,35,37,40],averchenkov:37,avoid:[3,29],awai:[2,3],await:[1,2,3,8,9,10,12,13,19,20,25,29,32,34,35,37,39,40,41],awar:40,awesom:[1,39],back:[1,2,3,10,13,19,25,32,37],backend:40,background:14,backport:[2,8,37,40],backward:37,bad:37,balanc:[3,20],bar:1,barancsuk:37,bare:[1,3],base:[5,8,10,11,15,16,17,19,20,21,22,23,25,26,28,29,30,31,32,40],base_exp:28,basedbapi:[23,24],baseexcept:[13,32],basemodel:40,basic:[2,3,4,20,38,39],batch:[4,20,41],bayer:[3,39],becaus:[1,2,3,8,12,13,19,20,32,37,40,41],becom:[2,12],been:[1,2,23,37],befor:[1,2,3,6,8,10,12,13,20,25,32,34,40,41],before_set:9,begin:[1,3,23,24],beginn:41,behav:[20,37],behavior:[2,8,13,20,25,34,37],behind:[2,3,10,20,37,40],being:[1,2,3,12,20],belong:13,below:[6,8,9,40],benefici:3,besid:8,best:[1,6,37,40],beta:37,better:[3,37,39],between:[1,2,3,37],beyond:3,biginteg:[19,34,40],bin:40,binari:[24,37],bind:[2,3,8,12,13,19,20,23,30,37,41],bind_processor:[2,23],bindtempl:23,binghan:37,birthdai:9,bit:[1,6,12,20,37,41],bite:[25,34],black:37,blade:1,blob:39,block:[1,2,3,13,25,32,34],blog:6,blue:2,bondar:39,book:[8,19,39,41],booker:41,bookings_idx_booker_room:41,bookings_idx_day_room:41,bookings_pkei:41,bool:[9,40],booleanproperti:[9,28],boost:1,borrow:[2,13,25,34,35],boss:1,bot:39,both:[2,3,8,10,12,19,20,21,23,32,37,41],bottleneck:[1,3],bound:[1,19,20,21,34,41],branch:6,brien:37,broken:37,browser:6,brutal:1,bryanforb:39,bsd:14,buffer:3,bug:[4,8,37,39],bugfix:6,build:[1,3,6,8,10,19,20,38],builder:[10,40],built:[8,12,14,20,21,25,35,37,40,41],builtin:[24,34,37],bulk:[3,4,25],bunch:5,busi:[1,3,12],c10k:1,cach:40,call:[1,2,3,8,10,13,18,19,20,21,23,25,29,32,37,40,41],call_next:8,callabl:[10,23,25,29,37],callableload:29,callback:1,caller:8,came:3,can:[1,2,3,4,5,6,10,11,12,13,19,20,21,25,29,32,34,35,37,40,41],candid:37,cannot:[1,2,10,37,40],canopi:39,canopytax:39,cap:3,captur:40,carefulli:1,cast:[9,40],categori:10,categories_1:10,categories_2:10,caught:32,caus:[2,3,13,25,34,35,37,41],cdi:39,celeri:3,certain:[3,34],chain:[2,3,19,20,29,37,41],challeng:3,chanc:[1,3],chang:[5,6,8,20,25,37,40,41],chat:3,check:[2,6,8,10,12,20,23,40,41],checkfirst:[23,30],checklist:40,checkout:6,child:[10,37],child_id:10,children:[10,32],chmod:6,choic:[3,8,10],choos:[3,37,41],classic:10,classmethod:[20,24,29],claus:[2,8,10,12,19,20,23,24,25,29,41],clean:[8,37,40],cleaner:40,cleanli:[3,25],cleanup:35,clear:3,cli:40,click:2,client:[3,6,39,40],clone:6,close:[2,3,13,19,23,24,25,32,34,37,41],cls:[9,21],cmd:40,code:[1,2,3,8,10,12,13,14,25,32,37,40,41],coin:3,col:10,collect:[20,40],collid:37,color:[2,23,24,25],colspec:23,coltyp:23,column:[2,4,5,9,10,12,19,20,21,23,25,29,34,37,39,40,41],column_kei:23,column_nam:20,columnattribut:21,columnload:[8,10,29],com:[6,8,14,39,40],combin:[2,10,41],come:12,command:[3,5,40,41],command_timeout:23,comment:25,commit:[3,6,13,23,24,25,32,37,40],common:[12,13,25,35,40],commun:[14,39],compani:29,compar:[1,3,20,40],compat:[2,8,25,29,37],compil:[19,24,25,41],complet:[2,8,19,37,40],complex:[1,4,10,39,41],complic:1,compos:[40,41],composit:20,comput:1,con:0,concentr:3,concept:[2,12,41],conceptu:12,conclus:3,concret:[2,12,21,34],concurr:[1,3],condit:[10,20,41],config:[8,11,34,35,37,40],configur:[6,15,29,33,34,40],confirm:37,conflict:[10,29],conftest:40,confus:2,congratul:5,conn1:2,conn2:2,conn:[2,3,12,19,23,24,25,32,37],connect:[0,3,4,10,12,13,15,19,23,25,30,32,33,34,37,38,40],connection_cl:25,connection_class:23,connectionless:2,conradi:37,consid:[3,8,37],consist:37,constant:1,constraint:[21,30,37,41],construct:[3,8,12,19,21],consum:3,contain:[5,8,21,41],content:[1,15,16],context:[1,2,3,8,13,14,19,23,24,25,29,32,34,35,37,39,40],contextu:[8,10,34],contextualgino:8,contextvar:[2,8,15,18,39],continu:[13,32],contrast:[1,3],contribut:[4,37],control:[1,4,23,25,34,37,40],conveni:[2,3,12,13,19,20,39,40,41],convers:[2,23],convert:29,cool:1,cooper:[0,3],copi:[8,25,37,40],core:[1,2,4,8,14,19,21,37,39,41],coroutin:[1,2,3,20,25,31],correctli:[3,12,13,19,20,37,40],correspond:[2,10,20,21],correspondingli:[2,13,32],cost:1,could:[1,2,3,6,8,10,20,40],count:[2,8,10,40,41],count_1:41,cours:40,cov:40,cover:[37,40,41],coverag:[37,40],cpu:1,cpython:39,creat:[0,3,4,6,8,10,12,13,19,20,21,23,25,29,30,31,32,34,35,37,38,39],create_al:[8,9,10,12,19,30,37,41],create_async:[23,30],create_engin:[2,3,8,11,12,17,19,25,29,31,37,41],create_ok:30,create_pool:[2,37],create_t:40,create_task:8,createdb:[40,41],creation:[2,8,19,37,40],credenti:5,credit:6,critic:1,cross:34,crt:6,crucial:13,crud:[2,3,4,8,10,12,15,16,17,19,25,37,38,39],crudmodel:[19,20,37],csrf:40,ctrl:40,ctx:10,cur:40,curatedlist:39,current:[1,2,8,11,13,17,20,23,25,37,40,41],current_connect:[0,25,37],current_databas:8,current_us:[3,39],cursor:[2,23,24,25],cursor_cl:[23,24],custom:[9,10,20,21,25,37],customiz:[21,37],cut:3,cutil:37,cve:40,dahlia:39,dai:41,daisi:[9,21,39,41],damn:1,danger:34,darwin:40,data:[1,2,8,9,10,20,40,41],databas:[0,2,4,5,6,9,10,12,13,19,20,21,23,25,29,32,34,35,37,39,40,41],datastructur:40,date:41,datetim:[8,9,10,21,29],datetimeproperti:[9,28],db_age:20,db_databas:[34,40],db_driver:40,db_dsn:40,db_echo:[8,34,37,40],db_host:[11,34,40],db_kwarg:[11,34],db_name:[5,6],db_pass:6,db_password:[34,40],db_pool_max_s:[34,40],db_pool_min_s:[34,40],db_port:[6,34,40],db_retry_interv:40,db_retry_limit:40,db_ssl:40,db_use_connection_for_request:[34,40],db_user:[6,34,40],dbapi:[23,24],dbapi_class:[23,24],dbapi_conn:23,dbapicursor:[23,24],dbname:[8,40],ddl:[30,40],dead:3,deadlock:3,deal:[1,3,8,10,13],debug:[1,34],decim:37,declar:[1,4,10,15,16,17,19,20,38],declarative_bas:21,declared_attr:[9,21,37,41],decod:28,decor:21,decreas:1,def:[1,2,3,8,9,10,12,21,23,34,40,41],defaultdialect:23,defer:3,defin:[4,5,9,10,11,12,19,21,25,29,40,41],definit:[8,10,21,40],del:8,delai:3,deleg:[2,12,19,20,37],delet:[10,12,20,37,38,40],delete_us:40,deliv:1,demo:40,demonstr:40,depend:[1,2,3,5,8,20,25,32,37,38,41],deploi:[3,40],deprec:[20,29,37],describ:[3,8,14],descript:[5,6,23,24,35,40],design:[2,3,8,41],detach:41,detail:[2,6,8,10,41],detect:40,determin:[3,10],deutel:37,dev:[39,40],develop:[5,6,15,34,40],diagram:[1,2,40],dialect:[2,8,9,11,14,15,16,17,25,30,32,35,37,41],dict:[2,8,9,11,20,21,29,37,40],dictionari:[2,25,34],did:37,didn:[2,3,27],differ:[1,2,3,4,9,10,12,19,20,21,25,37,40,41],difficult:1,dig:12,direct:[3,25,41],directli:[2,3,8,10,12,19,20,21,25,34,37,40,41],directori:[5,37,40],dirti:[8,37],disabl:[20,37],disable_inherit:37,disable_task_loc:37,disadvantag:3,disallow:8,disast:[13,34],discard:[2,20,25],disconnect:41,discord:39,discourag:3,discuss:8,disproportion:3,dist:37,distinct:[10,20,29,37],distinguish:2,divio:14,django:4,do_load:29,do_on_connect:23,doc:[5,6,8,13,37,39,40],docker:[6,40],dockerfil:40,docstr:6,document:[2,4,5,8,37,39,40,41],doe:[2,3,4,10,12,19,20,25,29,37,39,41],doesn:[2,3,8,9,10,21,37,40,41],doing:[1,3,19,37],don:[0,1,2,8,10,13,20,25,40,41],done:[0,1,2,5,6,8,12,13,37,40,41],doubl:1,doubt:10,down:[3,40],downgrad:[5,40],download:14,dramat:1,driven:6,driver:[2,8,13,23,25,35,37,41],drivernam:40,drop:[1,30,37,40],drop_al:[8,10,30],drop_async:[23,30],drop_ok:30,drop_tabl:40,dsn:[35,37,40],due:[3,37,41],dure:[1,2,21,25,34,37],dynam:[10,12,21],dziewulski:37,each:[1,2,3,5,8,10,21,25,29,34,41],earli:[13,14,15,32,35],earlier:[8,35],easi:[2,8,10],easier:[1,6,8],easili:[1,2,3,10],echo:[2,8,25,35,37,40],ecosystem:3,edg:1,edit:9,effect:[20,25,41],effici:[1,2],effort:3,either:[1,2,3,5,8,12,13,20,25,32,40],elem:[19,24],element:19,els:[2,3,8,12,13,25,34,40,41],email:[3,8],email_address:12,emerg:37,empti:[2,34,35,37,40],enabl:[2,6,8,20,21,29,35,37,40],enable_inherit:37,enable_task_loc:37,encapsul:[3,8,40],encod:[28,39],encourag:19,encrypt:6,end:[2,3,10,13,40,41],endpoint:3,enforc:[10,13],engin:[0,1,4,13,15,16,17,19,20,31,32,35,39,40,41],engine_cl:31,engine_from_config:19,enginestrategi:31,enhanc:[3,6,37],enjoi:34,enough:[3,40],ensur:37,enter:[13,19,25],entri:[12,27,40],entry_point:40,env:[5,8,40],environ:[6,37,40],equal:[2,20,37],equival:[20,21],error:[8,23,24,37],especi:[1,2,3,8,10,37,41],establish:34,etc:[23,40],even:[1,2,3,6,8,12,19,20,21,25,34,37,40,41],event:[1,3,6,23,37,39],eventlet:39,eventu:[2,8,40],ever:32,everi:[1,6,10,20],everyon:2,everyth:[2,3,8,12,13,34,41],exactli:[2,10,19,25,41],exampl:[1,2,3,5,6,8,10,11,12,13,19,20,25,29,32,34,37,40,41],except:[1,2,8,13,15,16,17,23,24,25,32,34,35,37],exchangeratesapi:39,exec:6,execut:[0,3,4,9,10,12,19,20,23,24,25,29,35,37,41],executemani:[24,25,37],execution_ctx_cl:23,execution_opt:[2,8,10,19,20,25,29,37],executioncontextoverrid:[23,24],exhaust:[2,3],exist:[2,3,4,19,20,21,23,35,37,41],exit:[13,19,25,32],exp:9,expect:29,experiment:[10,20,29],explain:[3,6,8,10,14,40],explan:[14,39],explicit:[0,2,8,10,13,37,39,41],explicitli:[2,3,8,9,32,34,41],explict:12,expos:[12,19,37],express:[4,9,20,25,29],ext:[8,11,15,16,17,19,34,35,37,40],extens:[2,8,11,12,15,19,27,34,35,37,38,41],extern:[1,41],extra:[1,29,37,40],extract:37,extrem:2,f2c273a43a3ed893a767d4239046f2befabf510d:39,face:3,facebook:39,fact:[8,23],factori:[21,35,40],fail:[2,19,37,40],fair:1,fals:[2,3,9,12,20,23,24,25,30,34,35,37,40],familiar:41,famou:1,fantix:[20,39,40,41],far:[12,41],fast:[3,34,39,40],fastapi:[3,8,38,39],faster:41,featur:[2,4,10,20,29,37,40,41],fed:[10,37],feed:[1,25,29,40],feedback:4,feel:[1,20,25,40,41],fetch:[1,25],few:[2,3,8,25,34,37],field:[8,9,12,20],file:[1,5,6,37,40],fill:29,filter:[20,41],find:[3,5,21,27,41],fine:[3,8,12],finish:[1,2,3,5,20,25,34,40],first:[1,2,3,4,6,8,10,12,19,20,23,24,25,29,34,35,37,40,41],first_connect:23,first_nam:8,first_or_404:37,firstli:10,fit:2,five:37,fix:[3,4,8,37,40,41],fixtur:40,flag:[23,35],flake8:6,flat:8,flexibl:[9,10,39],flow:3,flush:3,fly:4,focu:8,folder:5,follow:[2,3,8,9,13,19,29,32,40,41],footprint:1,forc:[1,3],foreign:[8,10,20],foreignkei:[8,10,12,39],forev:[20,25],forget:[2,41],fork:6,format:[8,34],former:2,fortun:3,forward:[10,23,24],found:[2,3,8,10,19,21,37,40,41],foundat:[3,39],founder:41,founding_us:41,fouser:19,framework:[1,8,37,40],free:[3,14,20,25,40,41],freebsd:39,freez:3,frequent:[4,10],friendli:[37,41],from:[1,2,3,5,8,9,10,11,12,13,14,19,20,21,25,29,32,34,35,37,39,40,41],fromclaus:29,frozen:40,full:[2,5,8,40],full_path:5,fulli:[25,40,41],fullnam:12,fun:[3,41],func:[8,10,29,41],fundament:3,further:[2,12,25,41],furthermor:[2,25,34],fut:8,futur:[8,10,40],gain:10,galden:37,garciasilva:39,gbasic:39,gcc:40,gener:[1,2,9,10,20,21,23,29,40],geoalchemi:39,get:[1,2,3,4,8,10,12,14,17,19,20,21,25,29,34,37,38,39,40],get_app:40,get_column:29,get_current_connect:37,get_event_loop:41,get_from:29,get_isolation_level:23,get_loc:37,get_now:2,get_or_404:[34,37,40],get_profil:28,get_raw_connect:25,get_result_proxi:24,get_statusmsg:[23,24],get_us:[34,40],get_vers:17,getattr:40,getlogg:40,getter:19,gevent:39,gino:[2,3,4,5,6,9,10,11,13,15,16,34,35,38],gino_db:6,gino_fastapi_demo:40,gino_fastapi_demo_test:40,gino_starlett:27,ginoconnect:[2,12,13,15,25,32],ginoengin:[2,8,12,13,19,20,25,29,31,32,37],ginoexcept:26,ginoexecutor:[2,19],ginonulltyp:23,ginopool:37,ginoschemavisitor:[12,19,30],ginostrategi:31,ginotransact:[13,25,32,37],git:[6,25,40],github:[6,8,14,39],gitignor:40,gitlab:39,gitter:14,give:[1,3,10,29],given:[2,6,8,10,19,20,21,23,25,29,31,40],global:[12,19,41],gmail:40,gnu:39,goe:41,golden:3,goncharov:37,gone:37,good:[1,25],got:1,gotta:1,grai:2,grammar:[3,8,37],grandson:10,great:[3,5,8],greater:[1,18],greatli:[1,2,6],green:[1,2],greenlet:8,group_bi:[8,10],guarante:[3,13,25,40],guess:3,guess_model:37,guid:[14,40,41],guidelin:4,gunicorn:40,hack:[8,40,41],had:[1,12,21],hadn:1,hand:[1,2],handl:[1,2,3,13,25,32,37],handler:34,hang:3,happen:[1,3,19,25,41],happi:40,hard:3,hardwar:3,harm:3,has:[1,2,3,8,10,12,13,19,20,23,25,37,41],has_schema:23,has_sequ:23,has_tabl:23,has_typ:23,haunt:3,have:[1,2,3,5,8,10,12,13,20,29,32,35,39,40,41],haven:40,head:[2,5,40],hei:[1,3],height:9,help:[0,1,6,13,41],henc:19,here:[1,2,3,6,8,9,10,12,13,20,25,32,37,40,41],herebi:19,hidden:2,hide:[2,37],hierarch:[8,10],hierarchi:40,high:[1,3],higher:40,histori:15,hit:3,hmm:2,hold:[1,8,13,40],holubakha:37,hong:39,honor:40,hood:[2,20,41],hook:[4,8,19,23,27],host:[23,35,40],how:[0,1,2,5,6,10,13,14,25,39,41],howev:[1,2,3,8,12,19,20,25,37],html:39,http:[1,5,6,8,14,25,39,40],hurri:1,hybrid:3,hyper:1,id_val:8,idea:3,ideal:[1,41],ident:[2,10,12,20,37,41],identifi:3,idl:3,ignor:40,imag:40,imagin:1,immedi:[2,3,20,25,32],immut:2,impair:1,impl:40,implement:[2,4,21,29,40,41],implic:12,implicit:[0,3,8,13,19,37,39],implicitli:[2,3,8,12,13,25,32],importantli:3,importlib:40,imposs:3,improv:[1,37],in_:10,in_queri:20,inc:39,includ:[6,8,20,35,37,40,41],include_foreign_key_constraint:30,include_rout:40,incomplet:40,increment:20,index:[1,4,10,21,30,39,41],index_on_nam:8,indic:[21,29,41],individu:[2,20,40],infer:20,info:40,inform:[2,8,12,13,19,25,41],inherit:[2,8,13,20,25,37,41],ini:[5,40],init:[5,23,37,40],init_app:[11,34,35,40],init_kwarg:23,init_pool:[23,24],initi:[2,4,9,12,20,21,23,29,31,35,40],inject:[2,12],inlin:[12,19,23,37],inner:[2,13,23],ins:12,insert:[4,12,13,20,25,37,39,41],insid:5,insist:10,inspir:[10,12],instal:[5,6,35,37,38,40],instanc:[2,3,5,8,9,10,12,13,19,20,21,23,25,28,29,31,37,40,41],instant:20,instanti:[12,20,25,29,40],instead:[1,2,3,10,12,13,20,21,25,27,37,40,41],integ:[5,8,9,10,12,21,39,41],integerproperti:[9,28],integr:[34,37,38],intend:21,intens:[1,3],interact:[40,41],interfac:[2,4,19,29,37],interfaceerror:23,interfer:37,interleav:1,intern:[2,8,10,13,20,21,32,37],internet:3,interpret:[10,32],interrupt:1,interv:23,introduc:[8,10,37],introduct:38,intuit:3,invalid:34,invent:8,invers:40,invert_get:21,invertdict:21,invok:[20,23],involv:[8,12],irrelev:19,is_:20,is_local_root:37,isdigit:34,ish:3,isol:[2,23,25,37],isolation_level:2,issu:[3,6,8,9,37,39,40],item:[10,12,29,30,40],iter:[2,8,10,12,19,20,21,23,24,25,37,39],its:[1,2,3,8,10,19,20,21,23,25,29,32,35,37,41],itself:[1,2,3,8,10,12,13,21,23,40],iuliia:37,jack:12,java:39,jeff:8,jekel:37,jetbrain:39,jim:37,job:25,join:[4,10,19,20,29,37,39],join_queri:10,join_without_n_plus_1:3,jone:[12,39],json:[4,20,23,34,37,40],json_support:[15,16,17,20],jsonb:[9,37],jsonpathtyp:[23,37],jsonproperti:[9,20,28],julio:37,just:[1,2,3,5,8,10,12,13,20,21,32,34,37,40,41],keep:[1,3,6,8,10,37,41],kei:[6,8,10,20,21,29,37,41],kentoseth:37,kept:[3,29],keyout:6,keyword:[2,8,10,20,29,41],kill:[1,3],kind:3,king:[39,40],kinwar:37,know:[1,2,3,8,13],knowledg:[10,12,20,41],known:[2,10,40,41],kooten:37,kovalev:37,kubernet:40,kwarg:[17,19,20,21,23,24,25,30,31,32,35,37],label:[29,37],lacerda:37,lambda:10,larg:[3,25],larger:[1,40],last:[1,2,3,10,19,20,32,40,41],last_nam:8,later:[1,2,8,10,12,25,35],latest:[20,25,39,40],latter:2,law:3,layer:3,layout:[37,40],lazi:[0,8,15,25,33,34,37],lazili:[2,34],lazy_engin:8,lead:[3,9],leaf:10,learn:[2,3],least:[1,3],leav:25,led:25,left:[2,10,20,39],legaci:12,len:10,length:12,lengthi:3,leosussan:39,less:[1,2,3,12],lesson:14,let:[1,2,3,10,12,13,40,41],level:[2,3,8,9,12,20,21,23,25,41],leverag:[3,9],lib:[6,40],libffi:40,librari:[37,39,40,41],licens:[14,39],liebig:3,lifetim:34,lightn:40,lightweight:[5,14],like:[1,2,3,5,6,8,9,10,12,20,21,25,27,34,35,40,41],likewis:[2,10,29,41],limit:[1,3,23,24,37,41],line:[2,5],linearli:1,link:[3,5,8,40],list:[2,6,8,9,12,25,29,40,41],listen:[3,23],liter:[1,25],littl:[1,6],live:[1,40],load:[2,3,4,10,19,20,25,29,37,39,40],load_modul:40,loader:[4,8,15,16,17,19,20,24,25,37,39],lobbi:14,local:[2,5,6,15,40],localhost:[3,6,8,10,11,12,29,34,35,40,41],locat:[20,37],lock:[3,40],log:[40,41],logger:40,logging_nam:[2,25],logic:[1,3,40],login:6,longer:[1,2,3,8,25,37],look:[1,3,6,10,20,35,40],lookup:[20,37],loop:[1,8,19,23,24,25,31,37,39],lose:25,lost:3,lot:[1,3,10],love:3,low:3,lower:[1,8,41],made:[8,10,12,37,40,41],magic:[2,10,41],magicstack:[8,39],mai:[1,2,3,8,9,10,13,19,25,34,40,41],main:[2,3,5,8,10,12,40,41],main_app:5,maintain:[3,8,21,39,40],mainten:37,major:3,make:[1,2,3,5,6,8,10,20,23,25,34,40,41],make_express:28,make_url:40,manag:[0,1,13,19,25,32,34,37,40,41],mandatori:12,mani:[2,3,4,6,8,23,24,25,37,41],manipul:37,manual:[4,8,9,10,12,20,25,32,37,40],map:[2,8,10,12,39,40,41],mapper:8,marissa:8,mark:[3,21,25],martin:37,masonri:40,mass:41,massiv:20,master:39,match:10,matter:[2,10,12],max:[2,40],max_cacheable_statement_s:23,max_cached_statement_lifetim:23,max_inactive_connection_lifetim:23,max_overflow:3,max_queri:23,max_siz:23,maximum:35,mean:[1,2,3,10,13,20,21,23,25,37,41],meaningless:[2,21],meant:[2,41],meanwhil:[20,32,37],meet:6,member:41,memori:[1,2,8,20,21,25,41],mention:[1,2,12,40,41],mess:[1,19],messag:[3,37],met:41,meta_path:27,metaclass:20,metadata:[2,8,12,19,20,21,30,37,39,40,41],method:[2,3,12,19,20,21,23,25,29,32,37,41],michael:39,middl:[1,35],middlewar:[8,35,37],might:[1,2,6],migrat:[4,15,40],mike:3,min:40,min_siz:[2,23],mind:1,minhe:39,minim:[1,12],minimum:3,misc:37,miser:3,miss:[2,37],mission:3,mistak:37,mix:3,mixin:[21,37,41],mkdir:40,mkvirtualenv:6,mock:29,mod:40,mode:[2,3,23,25,32,35,40],model:[2,3,4,5,8,9,12,19,20,21,24,25,29,34,37,38,39],model_base_class:19,model_class:[19,21],model_kei:8,modelload:[8,10,29,37],modern:3,modif:41,modifi:[10,40,41],modul:[2,5,8,15,16,37,40],modulenotfounderror:5,moment:[1,2,3],more:[1,2,3,6,8,10,12,13,19,20,21,25,37,41],morgan:37,most:[2,3,8,12,13,20,25,37,41],mostli:[3,20],move:[37,41],much:[1,2,3,9,12,13,25],multi:1,multiparam:[2,19,24,25,37],multipl:[1,2,4,10,25,29,37,41],multipleresultsfound:[25,26],multiplex:1,multitask:[0,3],musl:40,must:[1,2,3,5,8,12,19,25,29,40,41],mutabl:37,my_app:5,myapp:40,mydb:40,mydb_test:40,mydialect:23,mykyta:37,mymodel:40,myself:[1,3],mysql:[8,39,41],mytab:13,mytabl:13,myuser:20,name:[1,2,3,5,6,8,9,10,12,19,20,21,29,31,34,35,37,39,40,41],name_or_url:31,namespac:27,narrow:6,nativ:[9,37],natur:[1,3],neal:37,nearli:1,neat:3,necessari:[1,3,23,34],necessarili:2,need:[1,2,3,5,6,8,9,10,12,13,19,25,34,35,37,40,41],nest:[2,4,10,25,29,32],network:[1,2,3],never:[1,3,12,13,25,41],nevertheless:3,new_child:10,new_nam:8,new_names_dict:8,newcom:14,newli:[20,23,41],next:[1,3,5,12,23,24,25,40],nicknam:[5,12,34,40,41],no_deleg:19,non:[1,8,11,12,25,37,41],nonam:[5,12,41],none:[2,8,10,12,19,20,21,23,24,25,28,29,30,31,35,37,40,41],none_as_non:[15,20,29],noresultfound:[25,26],normal:[2,3,9,10,12,13,19,20,21,32,40,41],nosuchrowerror:26,note:[2,10,25,34,37,38,41],noth:[1,2,3,8,13,29,37],notic:[1,2,10],now:[1,2,3,5,6,8,10,12,13,14,19,25,29,37,40,41],nullabl:[9,12,40],nullpool:[11,23,37],nulltyp:23,number:[2,3,9,20,35,40],numer:24,obj:30,object:[2,3,5,8,9,10,12,19,20,21,23,24,25,28,29,30,32,37,39,40,41],objectproperti:[9,28],obviou:[1,3],obvious:[3,37],occasion:[3,19],occur:[1,23],off:[2,3,34,37],offer:[2,12,32,37],offici:[5,6,19,27],often:[19,20,21],okai:[1,40],olaf:37,old:[20,39],olexii:37,omit:[10,20],on_claus:[20,29],on_connect:23,onc:[1,2,3,5,8,10,23,25,41],one:[1,2,3,8,10,12,14,19,20,25,29,37,41],one_or_non:[2,12,19,25,37],ones:[2,3,19,29,40,41],onli:[1,2,3,5,10,11,12,13,14,19,20,21,25,29,32,35,40,41],ons:2,open:[5,6,13,25,39],openid:3,opensourc:39,openssl:[6,40],oper:[1,2,3,6,19,20,21,25,37,38,39,40],opposit:[3,25],opt:25,optim:2,option:[1,2,8,10,11,19,20,23,25,29,37,40],order:[1,2,8,10,20,25,40,41],ordinari:10,org:[5,39],origin:[6,12,20],orm:[0,2,4,10,14,39,41],orphan:2,orz:39,oss:39,other:[1,2,3,4,5,6,11,12,13,19,20,21,25,29,35,37,40,41],otherwis:[21,23,25,41],our:[1,3,5,40,41],out:[1,2,3,6,12,21,25,41],outer:[2,10,13,20],outerjoin:[8,10,29,37,39],output:[10,12],outsid:[1,41],over:[3,40],overal:[3,10],overhead:[1,3],overlap:1,overload:3,overrid:[19,20,21,37,40],overwrit:40,own:[1,2,3,8,10,11,12,40,41],owner:6,packag:[5,15,16,35,37,39,40],page:1,pai:34,pair:[10,20],parallel:[1,2],param:[19,24,25],paramet:[2,4,12,20,21,23,24,25,29,35,37,41],paramstyl:[2,24],parent:[2,8,10,12,19,32,37],parent_id:[8,10,37],parents_x_children:10,parentxchild:10,pars:[25,37],part:[1,2,3,6,8,40,41],partial:[2,8,37],particular:23,particularli:20,pascal:37,pass:[1,6,23,25,29,35,37,40],passfil:23,passin:6,passiv:37,passout:6,password:[5,6,23,35,40],patch:[8,18,37],patch_asyncio:18,patch_schema:30,path:40,pattern:[3,8,10],paus:1,pavol:37,payload:2,pem:6,pend:20,peopl:[3,10],pep:[37,39],per:[23,25],perform:[1,3,8,34],perman:[2,25,35,37],peter:39,pgcompil:23,pgdialect:23,pgexecutioncontext:23,pgjone:39,phase:40,philip:39,piec:[1,10,41],pip:[5,6,35,37,40,41],place:[21,25,37],plai:[2,3,19,25],plain:[2,8,39],plain_old_java_object:39,platform:[3,40],pleas:[1,2,6,8,9,10,12,13,19,25,34,37,40,41],plu:19,plugabl:40,pluggi:40,plugin:40,plural:41,poetri:[5,37,40,41],point:[1,3,25,27,40],poli:21,pool:[2,3,4,23,24,25,34,35,37,40],pool_class:[11,23],pool_max_s:[35,40],pool_min_s:[35,40],poolev:23,pop_bind:[2,19,37,41],popo:39,popul:[20,41],popular:[40,41],port:[3,12,23,35,40],posit:[20,23,25,29],possibl:[1,2,3,5,6,10,12,23,29,34,37,40,41],post:[2,6,10,40],postgi:39,postgr:[5,6,8,31,34,35,40],postgreserror:23,postgresql:[2,3,6,8,9,10,11,12,19,23,29,31,32,37,39,40,41],postgresqlimpl:40,postprocess:25,potenti:10,power:41,practic:[1,3,25,41],predict:1,preemptiv:1,prefer:[3,29,34,41],prefetch:37,prefix:31,prepar:[5,23,24,25,37],preparedstat:[23,24],present:[2,10,25,37],press:40,pretti:[3,12],prevent:37,previou:[1,2,10,12,19,35,37],previous:[1,2,10,40,41],primari:[20,37,41],primary_kei:[5,8,9,10,12,19,21,34,39,40,41],primarykeyconstraint:[40,41],princip:3,print:[4,9,10,12,20,39,41],prioriti:[3,40],privkei:6,pro:0,probabl:2,problem:[1,3,5,14,37],proce:23,process:[1,2,10,23,37,40,41],process_row:24,processor:[10,37],produc:[2,10],product:[0,38],profil:[9,28,37],program:[0,2,3,10,13,41],progress:2,prohibit:13,project:[5,6,8,38,41],promis:10,prop_nam:[9,21,28],propag:13,proper:3,properli:40,properti:[2,3,4,5,8,10,12,19,23,24,25,29,32,37,41],propos:6,protect:37,provid:[1,2,8,9,10,12,13,19,20,25,27,29,35,37,40],proxi:20,psql:6,psycopg2:[2,40],psycopg:40,publicli:[19,25],pull:4,pure:[8,37,41],push:6,put:[2,6,12,32],pwd:6,pycharm:39,pydant:40,pypi:[14,37],pyproject:40,pytest:[6,40],python:[1,2,3,5,6,8,9,14,18,21,27,37,38,40,41],pythongino:39,pythonpath:[5,40],qbasic:39,qualiti:3,quart:[37,39],queri:[0,3,4,6,9,10,12,15,19,20,21,23,24,25,29,35,39,41],query_executor:19,query_ext:19,query_param:8,querymodel:20,question:[3,4],queue:3,quick:[4,40],quickli:8,quit:[2,3,8,12,20,40,41],qulaz:37,rais:[2,8,13,19,25,32,37],raise_commit:[13,32],raise_for_statu:40,raise_rollback:[13,32],raiseerr:40,ran:1,randint:[8,10],random:[8,10],rang:[8,10,37],rather:[1,3,8,20,41],raw:[1,2,3,4,10,11,12,25,29,37,41],raw_conn:[23,24],raw_connect:[25,37],raw_pool:[23,24,25,37],raw_transact:[13,23,24,32],rdbm:[34,41],reach:[32,34],reaction:3,read:[1,2,8,19,20,21,25,41],read_root:3,readabl:1,readi:[1,6,40],readm:[6,37],real:1,realiti:3,realli:1,reason:[3,23],receiv:[1,8,23],recent:[2,25,41],recogn:[13,20,37],recommend:[2,19,25,34,41],reconsid:3,record:[37,41],recov:37,recurs:[10,25],recv:1,red:1,redirect:21,reduc:[10,12,40],refactor:37,refer:[2,8,10,13,14,19,25,41],referenc:[4,25,32],reflect:21,refresh:37,regardless:40,regist:1,regular:[10,12],reinvent:3,rel:5,relat:[2,8,10,39,40],relationship:[3,4,20,25,37],releas:[2,8,15,23,24,25,34,35,41],relev:[19,25,37],reli:3,reliabl:[3,40],reload:[20,28,40],remain:[8,37,40,41],rememb:[3,6,20,40,41],remind:3,remov:[2,20,37],renam:37,repeat:1,replac:[2,21,29,35,37],repli:3,repo:6,report:4,repositori:40,repr:[23,24,25],repres:[8,19,25,32,41],represent:37,reproduc:6,req:6,requeijo:37,request:[3,4,8,20,34,35,40],requir:[1,2,3,6,12,19,20,21,25,37,40,41],requirements_dev:6,reset:37,reset_loc:37,reskov:37,resourc:[1,2,3],respond:3,respons:[1,10,25,34,35],rest:[9,20,32,34,40,41],restart:40,restrict:19,result:[1,2,4,10,19,21,23,25,29,37,41],result_processor:[2,23],resum:[1,3,19],retri:40,retriev:[2,10,20,38,40],retry_interv:40,retry_limit:40,return_model:[2,19,20,24,25],reus:[0,3,10,13,25,29,34,37],reusabl:[0,25],revamp:37,revers:[2,12,25],revert:[2,37],review:[37,40,41],revis:[4,9,40],rewritten:[12,37],rewrot:37,ricardo:39,rich:[10,37],right:[0,40],risk:[2,12,41],roald:37,role:6,roll:[13,25,32],rollback:[3,13,23,24,25,32,37],roman:37,room:41,root:[3,25,40],rootdir:40,roughli:40,rout:34,router:40,row:[2,8,10,12,20,23,24,25,29,37,41],rowproxi:[2,12,29,37],rsa:6,rst:6,rule:[2,12,13,25,29],run:[1,2,3,4,5,6,9,10,25,29,34,35,40,41],run_until_complet:41,runtim:40,sa_conn:25,sacrific:3,safe:[1,12,25],sai:[1,3,34,40,41],said:[1,3],same:[1,2,3,4,5,9,10,12,13,19,20,21,25,29,34,35,37,40,41],sampl:[5,40],sanic:[11,15,33,37,39],sanicframework:39,save:[1,2,25,28,40],savepoint:[13,32],scalabl:3,scalar:[2,3,8,12,19,20,24,25,37,41],scale:1,scenario:[1,2,3,10,12,41],scene:[2,40],schedul:1,schema:[4,5,15,16,17,19,21,23,25,39,40,41],schema_ext:19,schema_for_object:25,schema_visitor:19,schemadropp:30,schemagener:30,schemaitem:[19,37],scope:[3,6,34],search:1,sec:1,second:[1,2,3,10,20,25],secret:40,section:[6,14],secur:[8,40],see:[1,2,5,6,8,12,13,25,40,41],seek:3,seem:[1,12],select:[2,3,8,9,10,12,13,19,20,25,29,37,39,41],select_from:[8,10,29],self:[4,8,9,19,20,23,25,29,34],send:[3,6,23],sens:3,sent:19,sep:10,separ:[3,6,10,13,37,40],sequenc:[2,23,30],sequence_nam:23,sequenti:1,sergei:37,seri:[2,25],serv:3,server:[2,3,6,8,25,34,35,37,38,41],server_default:[8,9,10],server_set:23,servic:[39,40],session:[3,40],sessionmak:3,set:[2,4,6,8,10,12,19,20,21,23,25,29,34,35,37,40,41],set_bind:[2,8,19,25,37,41],set_except:8,set_isolation_level:23,set_main_opt:40,set_result:8,setattr:[10,29,37],setter:[8,10,19],settl:34,setup:[5,6,23,35],sever:[1,2,19,20,25,41],shall:[13,20,34,40],share:[1,2,25,34,35,37],sharp:1,shini:40,shortcut:[2,3,10,13,17,19,20,25,29,40,41],shortest:3,should:[1,2,3,6,10,11,19,20,21,23,25,27,35,37,40,41],shouldn:[3,37],show:[10,40],shown:[2,32],shtrikker:37,shut:40,shutdown:40,side:[2,3,10,25],sign:1,silenc:1,simeon:37,similar:[1,2,5,6,10,12,13,19,20,37,40,41],similarli:[2,10,12,13,20,25,37],simpl:[1,2,3,5,8,12,19,37,38,39,41],simpler:[1,2,41],simplest:29,simpli:[1,2,3,8,9,10,19,20,25,29,34,35,40,41],simplic:1,simplifi:40,simul:[2,8],sinc:[1,20,37],singl:[1,2,3,10,12,20,23,25,41],singular:41,situat:[3,25,32],size:[1,40],skip:[13,32,40],sleep:[1,2,3],slice:1,slower:[3,41],small:[1,2],smaller:3,smarter:3,softwar:[14,39],sole:23,solut:[3,27,41],solv:[1,3,14],some:[1,2,3,5,6,8,9,10,12,20,25,35,37,40,41],someth:[1,2,3,10,40],sometim:[2,3,34,41],soon:34,sourc:[14,20,25,37,39,40],speak:[2,41],special:[10,23,34],specif:[2,14,20],specifi:[2,9,10,12,13,20,21,23,25,29,35,37,41],split:[1,41],sql:[2,3,4,9,10,12,19,20,23,25,30,37,39,41],sqlalchemi:[2,3,4,5,9,10,12,14,17,19,20,21,23,25,29,30,31,35,37,39,40,41],sqltype:23,src:[37,39,40],ssl:[4,6,23,35,37,40],ssl_cert_fil:6,ssl_key_fil:6,stabil:8,stabl:[37,39,41],stack:[2,25,37,40,41],standard:[2,3],stare:40,starleet:37,starlett:[8,15,27,33,37,39,40],start:[1,2,3,4,8,13,14,20,25,32,34,37,38,41],startup:40,starv:0,starvat:3,state:[1,3,41],stateless:[3,8],statement:[2,3,8,12,13,20,23,24,37,41],statement_cache_s:23,statement_compil:23,statu:[2,12,13,19,20,24,25,37,41],status_cod:40,stave:3,step:[1,2,3,6,14,40],stereotyp:3,stick:1,still:[1,2,3,8,10,12,21,25,29,32,37,40,41],stop:[3,13,34],storag:[21,37],store:[1,2,9,10,21,40],stori:0,storm:37,str:[3,9,29,40],straightforward:3,strang:41,strategi:[2,15,16,17,29],string:[2,8,9,10,12,19,20,21,23,25,34,37,39,41],stringproperti:[9,28],strongli:3,structur:[5,10,20,25],stub:39,stuff:41,style:[3,10,12,37],sub:[3,8,21,29,37,40],subclass:[2,12,19,21,29,32,37,41],subj:6,subload:10,submit:[4,40],submodul:[15,16],subpackag:[15,16],subqueri:[20,37],subset:6,succeed:25,success:5,successfulli:[32,41],sugar:3,suggest:[1,41],suit:[20,37],summari:3,support:[2,4,6,9,10,14,15,18,19,20,25,29,33,37,39,40,41],supports_native_decim:23,suppos:[2,21,29,32],sure:[1,3,6,10,25,34,40],svx:6,swagger:40,sweet:1,symbol:19,sync:8,synchron:[1,19],syntax:6,sys:27,system:[1,2,6,8,10,40],tabl:[4,5,10,12,13,19,20,21,23,30,37,40,41],table_nam:23,tableclaus:12,tag:6,take:[1,2,3,8,11,12,20,25,29],taken:[1,2,25,34],talk:3,target:[40,41],target_metadata:[5,8,40],task:[1,2,3,15,25,35],tast:[12,40],team:[1,20,37],team_id:20,technic:20,telegram:39,tell:[2,41],ten:[1,3],termin:[6,41],test:[6,37,38],test_aiohttp:6,test_crud:40,test_gino:6,test_us:40,testclient:40,text:[6,8,9,10,12,19,29,37],textual:[2,10],than:[1,2,3,8,10,11,13,20,21,25,39,41],thank:[1,2,37],thei:[1,2,3,6,8,10,12,13,20,21,25,37,40,41],them:[1,3,5,8,9,10,20,37,40,41],themselv:1,theoret:[3,37],therefor:[1,2,3,8,12,19,20,25,34,41],thi:[1,2,3,5,6,7,8,9,10,12,13,18,19,20,21,23,25,27,29,31,32,34,35,36,37,40,41],thing:[1,2,3,5,12,21,37],think:[1,3,8],third:[10,12],those:[3,25],though:[1,3,12,20,34,41],thought:40,thousand:[1,3],thread:[1,2,3],three:2,through:[2,4,6,10,13,19,27,37,40,41],throughput:[1,3],thu:[1,2,3,12,13,25,37],tiago:37,tiangolo:39,tim:39,time:[1,2,3,5,8,9,10,13,19,20,25,34,40],timeout:[19,20,23,24,25,37],timeouterror:25,timestamp:9,timezon:21,tini:3,tip:4,titl:[39,40],to_dict:[20,37,40],togeth:[1,2,25,32,40,41],token:3,toml:40,toni:[37,39],too:[1,2,3,8,12,13,25,40,41],tool:[3,5,39,40,41],toolkit:5,top:[2,3,8,12,14,25,40,41],tornado:[15,33,37,39],tortois:39,total:[1,3],touch:[13,32],touchabl:2,tox:6,track:[40,41],trackedmixin:21,tradit:[8,12,41],transact:[2,3,4,8,10,15,16,17,19,23,24,25,34,39,40],transform:10,translat:[2,9,10],trap:[13,32],travers:2,traverse_singl:30,treat:[2,10,21,25,31],tree:10,tri:[1,3,25,37,41],trigger:[1,3,21],trio:8,troubleshoot:6,truncat:41,tupl:[2,8,10,20,25,29],tupleload:[8,10,29,37],turn:[1,2,10,25,34,37],tutori:[12,14,39,40,41],twice:[2,4,23,41],twist:[3,39],two:[1,2,3,8,10,12,13,20,25,32,40,41],tx1:[13,32],tx2:[13,32],tx3:32,txt:6,type:[2,4,8,9,10,12,20,21,25,29,32,37,41],type_nam:23,typic:[3,8],ua1:10,ua2:10,ubuntu:39,uid:[10,40],ultim:3,ultra:39,unbind:19,unchang:41,under:[2,8,10,12,19,20,21,29,37,40,41],underli:[2,12,13,25,32,37],unfortun:3,unicod:[5,8,10,12,21,23,34,40,41],unifi:[2,37],uninitializederror:[8,26,37],uniqu:[2,10,41],unique_constraint:21,unique_id:21,uniqueconstraint:21,unix:39,unknown:[10,37],unknownjsonpropertyerror:26,unless:[2,3,20,41],unlik:1,unnam:[37,40],unnecessarili:34,unpin:37,unpredict:[1,3,34],unrecogn:35,unreli:3,unreus:2,unset:2,unspecifi:20,untest:2,until:[1,8,9,25],untouch:41,unus:[2,3],unwant:12,unwrap:23,updat:[2,4,6,9,20,21,25,29,32,37,38,39,40],update_execution_opt:[25,37],updaterequest:[20,41],upgrad:[2,5,8,37,40],upon:[13,23,32],upstream:8,urh:1,url:[2,5,19,23,24,31,35,37,40,41],usabl:[2,25,37],usag:[2,4,5,20,25,35,37],use:[1,2,3,4,5,6,9,10,11,12,13,19,20,23,25,27,29,32,34,35,37,39,40,41],use_connection_for_request:[35,40],used:[1,2,8,10,11,12,19,20,21,23,25,29,37,40,41],useful:[2,3,12,20,25,29,32],user1:20,user2:20,user:[2,3,4,5,6,9,10,11,12,19,20,21,23,25,29,32,34,35,39,40,41],user_id:[8,10,12,20,34],usermodel:40,usernam:[5,40],users_t:2,uses:[8,10,20,31,40],using:[1,2,3,6,8,10,12,13,20,21,23,25,29,37,40,41],usual:[1,2,3,8,9,10,12,19,20,21,25,40,41],utc:10,util:[21,27],uuid4:40,uuid:40,uvicorn:[39,40],uvicornwork:40,uvloop:[1,39],v7oze:25,val:[8,9,28],valid:12,valu:[2,8,10,12,13,19,20,21,23,25,28,29,34,37,40,41],valueload:29,van:37,vanilla:[2,12],vargovcik:37,vari:40,variabl:[5,39,40,41],variant:2,venv:40,veri:[1,2,3,9,10,12,20,23,25,32,34],version:[5,6,8,17,18,20,35,37,40],view:40,virtual:6,virtualenv:40,virtualenvwrapp:6,visit:[8,10,19],visit_foreign_key_constraint:30,visit_index:30,visit_metadata:30,visit_sequ:30,visit_t:30,visual:39,vladimir:37,volkova:37,volunt:6,wai:[2,3,6,8,9,10,12,13,19,25,40,41],wait:[1,3,9,13,20,25,40],wang:[37,39],wanna:[1,3],want:[1,2,3,5,6,12,19,20,25,34,40,41],ware:8,warn:[37,40],wast:[1,2,3],watch:[1,39],weakref:37,web:[1,6,8,37,39],websit:6,welcom:[6,12,37,39],well:[1,2,3,21],were:[1,3],what:[1,2,3,4,12,13,19,40],whatev:[2,3,10,20,25],wheel:3,when:[0,1,2,5,6,8,10,12,13,18,19,20,21,25,29,32,34,37,40,41],whenev:40,where:[2,3,8,9,10,12,19,20,25,29,32,40,41],wherea:1,whether:[6,25,32,37],which:[1,2,3,8,10,12,19,20,21,23,25,32,34,37,40,41],whichev:37,whoever:6,whole:[1,37,41],whose:[12,32,41],why:[0,1,10,41],wide:23,wider:41,wiki:39,wikipedia:39,wip:[7,34,36],wise:3,wish:[2,6,10,25],with_bind:[2,8,10,12,19,37],within:[1,3,13,23,25,34,37],without:[1,2,3,9,12,13,19,25,37],won:[1,2,3,8,12,13,32,37,40,41],wonder:1,word:41,work:[1,2,3,4,5,6,10,12,15,20,21,25,33,37,40,41],workaround:8,workdir:40,worker:40,world:[1,12,34],worri:[2,3,8,13,37],worth:[2,12],would:[1,3,6,8,10,19,20,29],wrap:[8,21],wrapper:[2,3,8,21,25,39],write:[1,2,3,4,8,10,38,41],written:[12,39],wrong:[1,3,37],wrote:[1,3],ww4ronfhiqi:39,www:39,x509:6,xss:40,xxx:[20,39],xxxx:4,yai:[1,8],yellow:1,yes:1,yet:[1,8,9,25],yield:[1,3,12,20,21,25,29,40],yml:40,you:[1,2,3,5,6,8,9,10,12,13,19,20,21,25,32,34,35,37,40,41],your:[1,2,3,5,6,8,10,12,13,19,25,37,40,41],your_name_her:6,yourdbnam:40,youtub:39,yurii:37,zen:39,zenof:39,zero:[20,25],zone:[9,10]},titles:["Explanation","Asynchronous Programming 101","Engine and Connection","Why Asynchronous ORM?","How-to Guides","Use Alembic","Contributing","CRUD","Frequently Asked Questions","JSON Property","Loaders and Relationship","Connection Pool","Schema Declaration","Transaction","Welcome to GINO\u2019s documentation!","Reference","API Reference","gino package","gino.aiocontextvars module","gino.api module","gino.crud module","gino.declarative module","gino.dialects package","gino.dialects.asyncpg module","gino.dialects.base module","gino.engine module","gino.exceptions module","gino.ext package","gino.json_support module","gino.loader module","gino.schema module","gino.strategies module","gino.transaction module","Extensions","Sanic Support","Starlette Support","Tornado Support","History","Tutorials","\u5b98\u5ba3\uff1aPython \u5f02\u6b65\u7f16\u7a0b\u518d\u6dfb\u4e00\u5229\u5668","Build a FastAPI Server","GINO Basics"],titleterms:{"\u4f18\u52bf\u4e0e\u4e0d\u8db3":39,"\u5148\u8bf4":39,"\u5173\u4e8e\u4f5c\u8005":39,"\u518d\u8bf4":39,"\u53c2\u8003\u6587\u732e":39,"\u5b98\u5ba3":39,"\u5efa\u8bbe\u793e\u4f1a\u4e3b\u4e49":39,"\u5f02\u6b65\u7f16\u7a0b\u518d\u6dfb\u4e00\u5229\u5668":39,"\u65b9\u4fbf\u5feb\u6377":39,"\u662f\u8c01":39,"\u7b80\u5355\u660e\u4e86":39,"new":40,One:10,The:1,Use:5,Useful:14,access:3,add:40,admin:8,advanc:10,aiocontextvar:[8,18],alemb:[5,8,40],api:[16,19,37,40],appli:5,ask:8,asynchron:[1,3],asyncio:[3,8],asyncpg:23,base:24,basic:[13,41],batch:8,bug:6,build:40,bulk:8,can:8,column:8,complex:8,con:1,configur:35,connect:[2,8,11,35,41],content:[17,22,27],contextvar:37,contribut:6,control:13,cooper:1,core:12,creat:[2,5,9,40,41],crud:[7,20,41],current_connect:2,databas:[3,8],declar:[12,21,41],defin:8,delet:41,depend:40,develop:37,dialect:[22,23,24],differ:8,django:8,document:[6,14],doe:8,don:3,done:3,earli:37,engin:[2,8,12,25,37],except:26,execut:[2,8],exist:8,explan:0,explicit:3,express:10,ext:27,extens:[33,40],fastapi:40,featur:[6,8],feedback:6,first:5,fix:6,fly:8,frequent:8,get:[6,41],gino:[8,12,14,17,18,19,20,21,22,23,24,25,26,27,28,29,30,31,32,37,39,40,41],ginoconnect:37,guid:4,guidelin:6,help:3,histori:37,hook:9,how:[3,4,8],implement:6,implicit:2,index:[8,9],initi:8,insert:8,instal:41,integr:40,interfac:8,introduct:41,join:8,json:9,json_support:28,lazi:[2,35],link:14,load:8,loader:[10,29],local:37,manag:2,mani:10,manual:13,migrat:[5,37],model:[10,40,41],modul:[17,18,19,20,21,22,23,24,25,26,27,28,29,30,31,32],multipl:8,multitask:1,nest:13,none_as_non:37,note:40,oper:41,orm:[3,8,12],other:10,packag:[17,22,27],paramet:8,pool:11,print:8,pro:1,product:[3,40],program:1,project:40,properti:9,pull:6,python:39,queri:[2,8,37],question:8,quick:9,raw:8,refer:[15,16],referenc:10,relationship:[8,10],releas:37,report:6,request:6,result:8,retriev:41,reus:2,reusabl:2,revis:5,right:3,run:8,same:8,sanic:34,schema:[12,30],self:10,server:40,set:5,simpl:40,sql:8,sqlalchemi:8,ssl:8,starlett:35,start:[6,9,40],starv:3,stori:1,strategi:31,submit:6,submodul:[17,22],subpackag:17,support:[8,34,35,36],tabl:8,task:37,test:40,through:8,tip:6,tornado:36,transact:[13,32,37],tutori:38,twice:8,type:6,updat:[8,41],usag:[10,13],use:8,user:8,welcom:14,what:8,when:3,why:3,work:[8,34,35],write:[6,40],xxxx:8}}) \ No newline at end of file diff --git a/docs/en/1.0/tutorials.html b/docs/en/1.0/tutorials.html new file mode 100644 index 0000000..7212625 --- /dev/null +++ b/docs/en/1.0/tutorials.html @@ -0,0 +1,232 @@ + + + + + + + + Tutorials - GINO 1.0.2.dev0 documentation + + + + + + + + + + + +

+ +

+ + + + + +

+ + + +

+ + HOME + + + CREDITS + + +

Tutorials

How-to Guides

Explanation

Reference

+ +

Tutorials¶

+ +

+ + +

+ + + +
+ This work is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License. +

+ +

Tutorials

+ + +

+ +

+ Add your language here. +

+ +

+ +

+ + + + + + + + + + + \ No newline at end of file diff --git a/docs/en/1.0/tutorials/announcement.html b/docs/en/1.0/tutorials/announcement.html new file mode 100644 index 0000000..e91da26 --- /dev/null +++ b/docs/en/1.0/tutorials/announcement.html @@ -0,0 +1,488 @@ + + + + + + + + 官宣：Python 异步编程再添一利器 - GINO 1.0.2.dev0 documentation + + + + + + + + + + + +

+ + +

Tutorials

How-to Guides

Explanation

Reference

+ +

官宣：Python 异步编程再添一利器¶

+
GINO 填补了国内外 asyncio ORM 领域的空白
+

随着 Tornado1 和 asyncio2 等框架的陆续涌现，Python 异步编程这个话题也在逐渐升温。在这个烧脑的异步世界里，有没有办法可以既方便快捷、又简单明了地访问数据库呢？GitHub 千星项目 +GINO 了解一下！

GINO 是谁¶

GINO 是一个“轻量级”异步 ORM 框架，它的全称是 GINO Is Not ORM，借鉴了 GNU is Not Unix +的递归定义3手法。所以，GINO 一定要全！部！大！写！如果像这样“Gino”就变成了人名，你肯定要问一句“这是谁”。

ORM，即关系对象映射（Object-Relational Mapping4），是一类开发人员喜闻乐见的效率工具，它们“极大地”提升了写代码的幸福指数。GINO 是用来访问数据库的，也提供了对象映射的工具，那为什么非说 +GINO 不是 ORM 呢？

因为物极必反，ORM 在带来生活便利的同时，也是 bug 生长的温床——传统 ORM 往往会选择牺牲明确性（explicitness）来换取便捷性（convenience），再加上 Python 得天独厚的灵活性（flexibility），创造出了一种爆炸式的化学反应。一旦代码初具规模，项目或多或少都会遇到 ORM 反噬的情景：性能莫名其妙的差、出问题找不到原因、为了鸡毛蒜皮的小事大动干戈。随便一句 current_user.name +都有可能触发一大堆意想不到的数据库调用，这代码你让我怎么调试？

传统 ORM 的学习曲线前平后陡，能在快速原型开发中大展身手，但应用到大型项目中却十分考验开发人员的平均水平。

所有这些问题如果再放进异步编程的环境里，那就是 O(n²) 的复杂度了——哦不，是 +O(2ⁿ)。这对于一款优秀的异步 ORM 框架来说是不可接受的，所以 GINO 是 ORM 但不是一个传统的 +ORM，正犹如 GNU 不是一个传统的 Unix 一样，形似而神不似。

所以在 2017 年创作之初，我就给 GINO 定下了两个业绩目标：1) 方便快捷，2) 简单明了。三年后的今天，我索性在 1.0 稳定版发布的前夕做个年终总结。

先说“方便快捷”¶

+
“方便快捷”主要说的是开发效率。
+

重视开发效率的概念对于写 Python 的同学来说可能并不陌生，某些场景下，开发人员的时间确实比机器的时间值钱。所以，传统 ORM 里的对象映射不能丢。

from gino import Gino
+db = Gino()
+class User(db.Model):
+    __tablename__ = "users"
+    id = db.Column(db.Integer, primary_key=True)
+    name = db.Column(db.String)
+

+

这么定义表结构甚至让人有点小兴奋。咦，为什么这么眼熟？

没有错，这就是 SQLAlchemy ORM5 的定义风格。GINO 并不是从头造轮子，而是在 SQLAlchemy +core6（SQLAlchemy 中负责构建 SQL 的底层核心）的基础上开发的。这么做除了能保持熟悉的味道（以节省学习和迁移成本），更重要的是带来了整个 SQLAlchemy 的生态环境：开箱即用的数据库变更管理工具 +Alembic7、各种 SQLAlchemy 的增强插件8、专业领域的 PostGIS/geoalchemy9等，GINO 全都兼容。

是不是十分方便、十分快捷？不止这样。

GINO 一站式地解决了常用 CRUD 快捷方式10、上下文管理（aiocontextvars11 12）、 +数据库事务封装和嵌套13、连接池管理和懒加载14等多项便捷功能，无额外依赖关系，即装即用。

daisy = await User.create(name="daisy")
+await daisy.update(name="Daisy").apply()
+

+

GINO 还提供了15各大流行异步 Web 框架的定制版插件，能叫上名字的像 Tornado1、aiohttp16、Sanic17、FastAPI18/Starlette19、Quart20什么的都有，从简单示范到生产环境的各种例子品种齐全，妈妈再也不用担心我不会集成 Web 框架了。

为了让不同应用场景下的用户体验到最大的善意，GINO 目前支持三种不同程度的用法，成功实现了对同期竞品 +asyncpgsa21 的降维打击：

最少侵入型22：SQLAlchemy core 原教旨主义者，只有异步执行时才用到 GINO。
终身不婚型23：天生厌恶“对象”，只愿定义“表”，空手接 SQL。
火力全开型24：最大程度的便利，非典型异步 ORM。

最后，虽然是 Python（绝不是黑哈），但 GINO 在执行效率上也没落下。基于 MagicStack 出品必属精品的、一秒可读百万行的 asyncpg25，以及 uvloop26（可选）的强力加持，GINO +跑起来也是可以飞快的，被广泛应用于诸如实时汇率、聊天机器人、在线游戏等高并发领域，深受俄罗斯和乌克兰人民的爱戴。

再说“简单明了”¶

+
Explicit is better than implicit.
+
Simple is better than complex.
+
–The Zen of Python, PEP 2027
+

Python 之禅完美表达了 GINO 的立场——明确性（explicitness）对于上了规模的异步工程项目来说尤为重要，因此 GINO 的很多设计都受到了明确性的影响。

比如说，GINO 的 Model 是完全无状态的普通 Python 对象（POPO28—— 例如前面的 User +类，它的实例 daisy 就是内存里面的常规对象，你可以用 daisy.name 访问属性，也可以用 +daisy.name = "DAISY" 来修改属性，或者用 u = User() 来创建新的实例，这些操作都不会访问数据库，绝对绿色环保无毒副作用。

等到需要操作数据库的时候，你一定会有感知的。比如执行 INSERT 要用 +u = await User.create()，而 UPDATE 则是 +await u.update(name="Daisy").apply()。

Hint

其中，u.update(name="Daisy") 与 u.name = "Daisy" 类似，都是只在内存里修改对象的属性，不同的是 u.update() 还会返回一个包含本次变更的中间结果，对其执行 await xxx.apply() 则会将这些变更应用到数据库里。

这里的 await 就是明确性的关键，意味着我们要跳出去执行数据库操作了。换句话说，没有 await +就没有数据库操作。

另一方面，对于如何将数据库查询结果组装成内存对象及其属性，GINO +也有一套精妙的显式机制——可定制化的加载器 loaders29。对于简单直观的一对一加载，GINO +自然是伺候到家的，比如用 u = await User.get(1) 可以直接获取到 ID 为 1 的用户对象。但是对于更复杂的查询，GINO 不会去无端猜测主人的意图，而全权交给用户来明确地定义。加载器的用法也是很简单的，比如一个用户可能写了很多本书：

class Book(db.Model):
+    __tablename__ = "books"
+    id = db.Column(db.Integer, primary_key=True)
+    title = db.Column(db.String)
+    author_id = db.ForeignKey("users.id")
+

+

然后这样来加载这种多对一关系，以同时获取所有的书和他们的作者：

query = Book.outerjoin(User).select()
+loader = Book.load(author=User)
+async for book in query.gino.load(loader).iterate():
+    print(book.title, "written by", book.author.name)
+

+

很简单的一个外连接查询 Book.outerjoin(User)，配合一个直观的加载器 +Book.load(author=User)，就实现了：

执行 SELECT * FROM books LEFT JOIN users ON ...；
将数据库返回结果的每一行中，属于 books 的字段加载成一个 Book 实例；
然后将该行中剩下的属于 users 的字段加载成一个 User 实例；
最后将 User 实例设置到 Book 实例的 author 属性上。

既简单又明了有没有！你甚至可以手写任何 SQL，然后定制加载器自动加载成期望的对象关系，精准控制加载行为，指哪儿打哪儿。GINO 还有很多类似的特性，在这里就不一一列举了。

优势与不足¶

随着这几年 GINO 不断演进成熟，Python 开源社区里也相继出现了像 Tortoise +ORM30、ORM31（是的，这个项目就叫 ORM……我真 ORZ。出品方是 Encode，Starlette +就是他们的作品）等优秀的异步 ORM 框架。它们关注的重点与 GINO 稍有不同，但都是同行就不多评价了。

GINO 的最大优势还是在于充分平衡了开发效率和明确性之间的辩证矛盾关系，用 GINO 开发应用程序的时候不用担心会被意料之外的行为所惊吓到，同时也不需要为这种明确性付出过大的工程代价，上手后依然可以快速、快乐地编程。同时，大量的成功案例也证明了 GINO 已经初步具备发布 1.0 稳定版的各种条件，可以谨慎地用于生产环境了。

以下是近来统计到的关于 GINO 的应用案例：

笔者工作上开发的一个服务：https://github.com/uc-cdis/metadata-service
还是笔者自己写的一个工具：https://github.com/fantix/aintq
一个汇率 API 服务：https://exchangeratesapi.io/
+ +
各种 Telegram、Discord 的 Bot。
ArchLinux 用户包：https://aur.archlinux.org/packages/python-gino/
+ +
https://github.com/bryanforbes/gino-stubs/
俄语教程：https://www.youtube.com/watch?v=WW4rOnfhiQY
高性能模板项目：https://github.com/leosussan/fastapi-gino-arq-uvicorn
还有几个商用的，但没征得同意就不贴出来了。

另外，GINO 还贴心地提供了中文文档32，从上手教程到原理说明应有尽有（虽然文档还在努力编写中！）：

GINO 目前的不足之处还有一些，比如没有照顾到 Python 3 的类型提示，因此还不能完全发挥 IDE 的潜能（上面那个 gino-stubs 就是有人受不了了自己写了一个类型注解）。MySQL 目前也是不支持的，但 GINO +从比较早就解耦了不同 SQL 方言和驱动的集成，所以这些功能会陆续在 1.1 和 1.2 版本中跟上。

建设社会主义¶

GINO 是一个开源项目，所以欢迎大家一起来建设！长期活跃的贡献者还能获赠价值 4888 元的 PyCharm +专业版全家桶 License 一枚33（没有发票）。

目前急需帮助的有：

各个 Web 框架插件的维护工作需要多人认领；
更多的例子和文档，以及中文、俄文的翻译；
MySQL 的支持。

以及下面这些一直需要的帮助：

用 GINO，找 bug，提建议；
修 bug，做功能，提 PR；
维护社区，回答问题，参与讨论；
最后也是最重要的：去 GitHub 上给 GINO 加一颗星星！

关于作者¶

87 年生人，6 岁开始接触编程，二十五六年的编程史和十三四年的工作经验教会了我许多软件开发的奥义。小时候写 GBasic、QBasic 和 Visual Basic；大学里开始写 Java 并接触到了 FreeBSD 和 Ubuntu +等开源项目且一发不可收拾；工作头五年转向了 Python，通过 Twisted 和 Eventlet 等项目了解了异步编程，期间贡献了 Gevent 的 Python 3 迁移；也曾在创业的潮流中留下身影，亲身经历并见证了软件技术随着手游、新媒体、矿圈、互金、电商、社交、文娱、汽车等行业的起起伏伏；目前在芝大继续做生物大数据相关的开源项目。业余时间除了开发维护 GINO 项目外，还会偶尔修一修 uvloop、asyncpg 和 CPython 的 bug :P

特别感谢 Tony Wang 对 GINO 项目的贡献，以及所有人的贡献。

参考文献¶

1(1,2): Facebook. Tornado. https://zh.wikipedia.org/wiki/Tornado.
+
2: Python Software Foundation. asyncio — 异步 I/O. +https://docs.python.org/zh-cn/3/library/asyncio.html.
+
3: 维基百科. GNU. https://zh.wikipedia.org/wiki/GNU.
+
4: 维基百科. 对象关系映射. +https://zh.wikipedia.org/wiki/对象关系映射.
+
5: 维基百科. SQLAlchemy. https://zh.wikipedia.org/wiki/SQLAlchemy.
+
6: Michael Bayer. SQLAlchemy Core - SQLAlchemy. Documentation. +https://docs.sqlalchemy.org/en/13/core/index.html.
+
7: Michael Bayer. Welcome to Alembic’s documentation!. +https://alembic.sqlalchemy.org/en/latest/.
+
8: Hong Minhee. A curatedlist of awesome tools for SQLAlchemy. +https://github.com/dahlia/awesome-sqlalchemy.
+
9: Ricardo GarciaSilva. Does it have postgis support?. +https://github.com/python-gino/gino/issues/627.
+
10: Fantix King. GINO 基础教程 - 增删改查. +https://python-gino.org/docs/zh/master/tutorials/tutorial.html#crud-operations.
+
11: Python Software Foundation. contextvars —Context Variables. +https://docs.python.org/3/library/contextvars.html.
+
12: Fantix King. gino/aiocontextvars.py. +https://github.com/python-gino/gino/blob/f2c273a43a3ed893a767d4239046f2befabf510d/src/gino/aiocontextvars.py.
+
13: Fantix King. 数据库事务. +https://python-gino.org/docs/zh/master/how-to/transaction.html.
+
14: Fantix King. 引擎与连接. +https://python-gino.org/docs/zh/master/explanation/engine.html.
+
15: GINO Community. GINO Community. https://github.com/python-gino/.
+
16: aiohttp maintainers. Welcome to AIOHTTP. https://docs.aiohttp.org/en/stable/.
+
17: Sanic Community. SanicFramework. https://sanicframework.org/.
+
18: Sebastián Ramírez. FastAPI. https://fastapi.tiangolo.com/.
+
19: Encode OSS. Starlette. https://www.starlette.io/.
+
20: Philip Jones. Quart Documentation. https://pgjones.gitlab.io/quart/.
+
21: Canopy. asyncpgsa - A wrapper around asyncpg for use with sqlalchemy. +https://github.com/CanopyTax/asyncpgsa.
+
22: Fantix King. 表结构定义 -GINO 引擎. +https://pythongino.org/docs/zh/master/how-to/schema.html#gino-engine.
+
23: Fantix King. 表结构定义 - GINO core. +https://python-gino.org/docs/zh/master/how-to/schema.html#gino-core.
+
24: Fantix King. 表结构定义 - GINO ORM. +https://python-gino.org/docs/zh/master/how-to/schema.html#gino-orm.
+
25: MagicStack Inc. +asyncpg - A fast PostgreSQL Database Client Library for Python/asyncio. +https://github.com/MagicStack/asyncpg.
+
26: MagicStack Inc. uvloop -Ultra fast asyncio event loop. +https://github.com/MagicStack/uvloop.
+
27: Tim Peters. PEP ‒ The Zenof Python. https://www.python.org/dev/peps/pep-0020/.
+
28: Wikipedia. Plain old Java object. +https://en.wikipedia.org/wiki/Plain_old_Java_object.
+
29: Fantix King. 加载器与关系. +https://python-gino.org/docs/zh/master/how-to/loaders.html.
+
30: Andrey Bondar. Tortoise ORM. https://tortoise.github.io/.
+
31: Encode OSS. ORM - An async ORM. https://github.com/encode/orm.
+
32: Fantix King. 欢迎来到 GINO 的文档！. +https://python-gino.org/docs/zh/master/index.html.
+
33: JetBrains s.r.o. Open Source Licenses. +https://www.jetbrains.com/community/opensource/#support.
+

+ + +

+ + + +
+ This work is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License. +

+ +

官宣：Python 异步编程再添一利器
- GINO 是谁
- 先说“方便快捷”
- 再说“简单明了”
- 优势与不足
- 建设社会主义
- 关于作者
- 参考文献
+

+ + +

+ +

+ Add your language here. +

+ +

+ +

+ + + + + + + + + + + \ No newline at end of file diff --git a/docs/en/1.0/tutorials/fastapi.html b/docs/en/1.0/tutorials/fastapi.html new file mode 100644 index 0000000..205c34d --- /dev/null +++ b/docs/en/1.0/tutorials/fastapi.html @@ -0,0 +1,734 @@ + + + + + + + + Build a FastAPI Server - GINO 1.0.2.dev0 documentation + + + + + + + + + + + +

+ + +

Tutorials

How-to Guides

Explanation

Reference

+ +

Build a FastAPI Server¶

In this tutorial, we’ll build a production-ready FastAPI server together. +The full functional example is available here.

Our application stack will look like this:

Start a New Project¶

Instead of pip, let’s use the shiny Poetry to manage our project. Follow the link to +install Poetry, and create our new +project in an empty directory:

$ mkdir gino-fastapi-demo
+$ cd gino-fastapi-demo
+$ git init
+$ poetry init
+

+

Then follow the Poetry guide to finish the initialization - you may say “no” to the +interactive dependency creation, because we will add them manually. It is okay to use +the default values in the other steps of the guide, and make sure the package name +remains gino-fastapi-demo.

Add Dependencies¶

FastAPI is built on top of the Starlette framework, so we shall use the GINO +extension for Starlette. Simply run:

$ poetry add gino[starlette]
+

+

Then let’s add FastAPI, together with the lightning-fast ASGI server Uvicorn, and +Gunicorn as a production application server:

$ poetry add fastapi uvicorn gunicorn
+

+

For database migration, we’ll use Alembic. Because it uses normal DB-API, we need +psycopg here too:

$ poetry add alembic psycopg2
+

+

At last, let’s add pytest in the development environment for testing. We also want to +add the requests library to use the Starlette TestClient:

$ poetry add -D pytest requests
+

+

Hint

With the steps above, Poetry will automatically create a virtualenv for you +behind the scene, and all the dependencies are installed there. We will assume +using this for the rest of the tutorial. But you’re free to create your own +virtualenv, and Poetry will honor it when it’s activated.

That’s all, this is my pyproject.toml created by Poetry, yours should look similar:

[tool.poetry]
+name = "gino-fastapi-demo"
+version = "0.1.0"
+description = ""
+authors = ["Fantix King <fantix.king@gmail.com>"]
+
+[tool.poetry.dependencies]
+python = "^3.8"
+gino = {version = "^1.0", extras = ["starlette"]}
+fastapi = "^0.54.1"
+uvicorn = "^0.11.3"
+gunicorn = "^20.0.4"
+alembic = "^1.4.2"
+psycopg2 = "^2.8.5"
+
+[tool.poetry.dev-dependencies]
+pytest = "^5.4.1"
+requests = "^2.23.0"
+
+[build-system]
+requires = ["poetry>=0.12"]
+build-backend = "poetry.masonry.api"
+

+

And there’s also an auto-generated poetry.lock file with the frozen versions. The +directory layout should look like the diagram on the right. Now let’s add the two files +to the Git repository (we will skip showing these git operations in future steps):

$ git add pyproject.toml poetry.lock
+$ git commit -m 'add project dependencies'
+

+

Write a Simple Server¶

Now let’s write some Python code.

We’ll create an extra src directory to include all the Python files, as demonstrated +in the diagram below. This is known as the “src layout” providing a cleaner hierarchy.

The root Python package of our project is named as gino_fastapi_demo, under which we +will create two Python modules:

asgi as the ASGI entry point - we’ll feed it to the ASGI server
main to initialize our server

Here’s main.py:

from fastapi import FastAPI
+
+def get_app():
+    app = FastAPI(title="GINO FastAPI Demo")
+    return app
+

+

And we’ll simply instantiate our application in asgi.py:

from .main import get_app
+
+app = get_app()
+

+

Then run poetry install to link our Python package into the PYTHONPATH in +development mode. We’ll be able to start a Uvicorn development server after that:

$ poetry install
+Installing dependencies from lock file
+
+No dependencies to install or update
+
+  - Installing gino-fastapi-demo (0.1.0)
+
+$ poetry run uvicorn gino_fastapi_demo.asgi:app --reload
+INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
+INFO:     Started reloader process [53010]
+INFO:     Started server process [53015]
+INFO:     Waiting for application startup.
+INFO:     Application startup complete.
+

+

The --reload option enables Uvicorn to automatically reload the server for us when +the Python source code is updated. Now access http://127.0.0.1:8000/docs to see the +Swagger UI of our new FastAPI server.

Hint

As mentioned previously, if you’re in your own virtualenv, the command poetry run +uvicorn can be simplified as just uvicorn.

poetry run is a convenient shortcut to run the following command in the +virtualenv managed by Poetry.

Add GINO Extension¶

Now let’s add GINO to our server.

First of all, we need a way to configure the database. In this tutorial, we’ll use the +configuration system from Starlette. +Add src/gino_fastapi_demo/config.py as follows:

from sqlalchemy.engine.url import URL, make_url
+from starlette.config import Config
+from starlette.datastructures import Secret
+
+config = Config(".env")
+
+DB_DRIVER = config("DB_DRIVER", default="postgresql")
+DB_HOST = config("DB_HOST", default=None)
+DB_PORT = config("DB_PORT", cast=int, default=None)
+DB_USER = config("DB_USER", default=None)
+DB_PASSWORD = config("DB_PASSWORD", cast=Secret, default=None)
+DB_DATABASE = config("DB_DATABASE", default=None)
+DB_DSN = config(
+    "DB_DSN",
+    cast=make_url,
+    default=URL(
+        drivername=DB_DRIVER,
+        username=DB_USER,
+        password=DB_PASSWORD,
+        host=DB_HOST,
+        port=DB_PORT,
+        database=DB_DATABASE,
+    ),
+)
+DB_POOL_MIN_SIZE = config("DB_POOL_MIN_SIZE", cast=int, default=1)
+DB_POOL_MAX_SIZE = config("DB_POOL_MAX_SIZE", cast=int, default=16)
+DB_ECHO = config("DB_ECHO", cast=bool, default=False)
+DB_SSL = config("DB_SSL", default=None)
+DB_USE_CONNECTION_FOR_REQUEST = config(
+    "DB_USE_CONNECTION_FOR_REQUEST", cast=bool, default=True
+)
+DB_RETRY_LIMIT = config("DB_RETRY_LIMIT", cast=int, default=1)
+DB_RETRY_INTERVAL = config("DB_RETRY_INTERVAL", cast=int, default=1)
+

+

This config file will load from environment variable first, if not found then from a +file named .env from current path (usually the project root directory), and at last +use the default value defined above. For example, you can either overwrite in CLI +directly like this:

$ DB_HOST=localhost DB_USER=postgres poetry run uvicorn gino_fastapi_demo.asgi:app --reload
+

+

Or set them in the file .env (this file must not be committed into Git, remember to +add it to .gitignore):

DB_HOST=localhost
+DB_USER=postgres
+

+

Now it’s time to create a PostgreSQL database and set the connection variables +correctly here. This is usually something like createdb yourdbname, but it may vary +across different platforms, so we won’t cover this part in this tutorial.

Tip

Alternatively, you could also set DB_DSN to for example +postgresql://user:password@localhost:5432/dbname to override the other individual +config values like DB_HOST defined before DB_DSN.

If defined, DB_DSN always have the higher priority over the individual ones, +regardless of where they are defined - even if DB_HOST is defined in environment +variable and DB_DSN is defined in .env file, DB_HOST is still ignored. +Default value doesn’t count.

Then, create a new Python sub-package gino_fastapi_demo.models to encapsulate +database-related code, and add the code below to +src/gino_fastapi_demo/models/__init__.py:

from gino.ext.starlette import Gino
+
+from .. import config
+
+db = Gino(
+    dsn=config.DB_DSN,
+    pool_min_size=config.DB_POOL_MIN_SIZE,
+    pool_max_size=config.DB_POOL_MAX_SIZE,
+    echo=config.DB_ECHO,
+    ssl=config.DB_SSL,
+    use_connection_for_request=config.DB_USE_CONNECTION_FOR_REQUEST,
+    retry_limit=config.DB_RETRY_LIMIT,
+    retry_interval=config.DB_RETRY_INTERVAL,
+)
+

+

At last, modify src/gino_fastapi_demo/main.py to install the GINO extension:

 from fastapi import FastAPI
++
++from .models import db
+
+ def get_app():
+     app = FastAPI(title="GINO FastAPI Demo")
++    db.init_app(app)
+     return app
+

+

Saving the file, you should see the Uvicorn server reloads our changes and connects to +the database:

WARNING:  Detected file change in 'src/gino_fastapi_demo/main.py'. Reloading...
+INFO:     Shutting down
+INFO:     Waiting for application shutdown.
+INFO:     Application shutdown complete.
+INFO:     Finished server process [63562]
+INFO:     Started server process [63563]
+INFO:     Waiting for application startup.
+INFO:     Connecting to the database: postgresql://fantix:***@localhost
+INFO:     Database connection pool created: <asyncpg.pool.Pool max=16 min=1 cur=1 use=0>
+INFO:     Application startup complete.
+

+

Create Models and API¶

../_images/gino-fastapi-models-users.svg

It’s time to implement the API now. Let’s say we are building a user management service, +through which we could add users, list users and delete users.

First of all, we need a database table users to store the data, mapped to a GINO +model named User. We shall add the model in gino_fastapi_demo.models.users:

from . import db
+
+class User(db.Model):
+    __tablename__ = "users"
+
+    id = db.Column(db.BigInteger(), primary_key=True)
+    nickname = db.Column(db.Unicode(), default="unnamed")
+

+

The model definition is simple enough to explain itself.

Then we only have to use it properly in the API implementation, for which we’ll create a +new Python sub-package gino_fastapi_demo.views, and a new module +gino_fastapi_demo.views.users as follows:

from fastapi import APIRouter
+from pydantic import BaseModel
+
+from ..models.users import User
+
+router = APIRouter()
+
+@router.get("/users/{uid}")
+async def get_user(uid: int):
+    user = await User.get_or_404(uid)
+    return user.to_dict()
+
+class UserModel(BaseModel):
+    name: str
+
+@router.post("/users")
+async def add_user(user: UserModel):
+    rv = await User.create(nickname=user.name)
+    return rv.to_dict()
+
+@router.delete("/users/{uid}")
+async def delete_user(uid: int):
+    user = await User.get_or_404(uid)
+    await user.delete()
+    return dict(id=uid)
+
+def init_app(app):
+    app.include_router(router)
+

+

The APIRouter holds our new APIs locally, and init_app is used to integrate it +into our FastAPI application. Here we want some inversion of control: let’s make the +APIs plugable, so that we don’t have to import all possible future views manually. We +shall use the Entry Points feature to load the dependencies. Add this code below to +gino_fastapi_demo.main:

import logging
+from importlib.metadata import entry_points
+
+logger = logging.getLogger(__name__)
+
+def load_modules(app=None):
+    for ep in entry_points()["gino_fastapi_demo.modules"]:
+        logger.info("Loading module: %s", ep.name)
+        mod = ep.load()
+        if app:
+            init_app = getattr(mod, "init_app", None)
+            if init_app:
+                init_app(app)
+

+

Hint

If you’re running Python < 3.8, you’ll need this importlib-metadata backport.

And call it in our application factory:

 def get_app():
+     app = FastAPI(title="GINO FastAPI Demo")
+     db.init_app(app)
++    load_modules(app)
+     return app
+

+

Finally, define the entry points in pyproject.toml following the Poetry document +for plugins:

[tool.poetry.plugins."gino_fastapi_demo.modules"]
+"users" = "gino_fastapi_demo.views.users"
+

+

Run poetry install again to activate the entry points - you may need to restart the +Uvicorn development server manually, as the reloader cannot capture the changes we made +to pyproject.toml.

Now you should be able to see the 3 new APIs on the Swagger UI. But none of them works, +because we still haven’t created the database tables.

Integrate with Alembic¶

To get started with Alembic, run this command in the project root directory:

$ poetry run alembic init migrations
+

+

This will generate a new directory migrations where Alembic will store database +migration revisions. At the same time, an alembic.ini file is created in the project +root directory. Let’s simply add all of them to Git control.

For Alembic to use our data models defined with GINO (and of course the database +config), we need to modify migrations/env.py to connect with the GINO instance:

 # add your model's MetaData object here
+ # for 'autogenerate' support
+ # from myapp import mymodel
+ # target_metadata = mymodel.Base.metadata
+-target_metadata = None
++from gino_fastapi_demo.config import DB_DSN
++from gino_fastapi_demo.main import db, load_modules
++
++load_modules()
++config.set_main_option("sqlalchemy.url", str(DB_DSN))
++target_metadata = db
+

+

Then create our first migration revision with:

$ poetry run alembic revision --autogenerate -m 'add users table'
+INFO  [alembic.runtime.migration] Context impl PostgresqlImpl.
+INFO  [alembic.runtime.migration] Will assume transactional DDL.
+INFO  [alembic.autogenerate.compare] Detected added table 'users'
+  Generating migrations/versions/32c0feba61ea_add_users_table.py ...  done
+

+

The generated revision file should roughly look like this:

def upgrade():
+    op.create_table(
+        "users",
+        sa.Column("id", sa.BigInteger(), nullable=False),
+        sa.Column("nickname", sa.Unicode(), nullable=True),
+        sa.PrimaryKeyConstraint("id"),
+    )
+
+def downgrade():
+    op.drop_table("users")
+

+

Hint

Whenever there is a change to the database schema in the future, just modify the +GINO models and run alembic revision --autogenerate again to generate new +revisions to track the change. Remember to review the revision file - you may want +to adjust it.

Eventually, let’s apply this migration, by upgrading to the latest revision:

$ poetry run alembic upgrade head
+INFO  [alembic.runtime.migration] Context impl PostgresqlImpl.
+INFO  [alembic.runtime.migration] Will assume transactional DDL.
+INFO  [alembic.runtime.migration] Running upgrade  -> 32c0feba61ea, add users table
+

+

Now all the APIs should be fully operational, try with the Swagger UI.

Write the Tests¶

In order not to break our development database with running tests, let’s create a +separate database to run tests. Apply this change to gino_fastapi_demo.config:

 config = Config(".env")
+
++TESTING = config("TESTING", cast=bool, default=False)
+
+ DB_DRIVER = config("DB_DRIVER", default="postgresql")
+ DB_HOST = config("DB_HOST", default=None)
+ DB_PORT = config("DB_PORT", cast=int, default=None)
+ DB_USER = config("DB_USER", default=None)
+ DB_PASSWORD = config("DB_PASSWORD", cast=Secret, default=None)
+ DB_DATABASE = config("DB_DATABASE", default=None)
++if TESTING:
++    if DB_DATABASE:
++        DB_DATABASE += "_test"
++    else:
++        DB_DATABASE = "gino_fastapi_demo_test"
+ DB_DSN = config(
+

+

Hint

You need to run createdb to actually create the database. If you have set +DB_DATABASE in .env - e.g. DB_DATABASE=mydb, the name of the testing +database should be mydb_test. Or else, gino_fastapi_demo_test.

Then, let’s create our pytest fixture in tests/conftest.py:

import pytest
+from alembic.config import main
+from starlette.config import environ
+from starlette.testclient import TestClient
+
+environ["TESTING"] = "TRUE"
+
+@pytest.fixture
+def client():
+    from gino_fastapi_demo.main import db, get_app
+
+    main(["--raiseerr", "upgrade", "head"])
+
+    with TestClient(get_app()) as client:
+        yield client
+
+    main(["--raiseerr", "downgrade", "base"])
+

+

This fixture creates all the database tables before running the test, yield a Starlette +TestClient, and drop all the tables with all the data after the test to maintain a +clean environment for the next test.

Here’s a sample test in tests/test_users.py:

import uuid
+
+def test_crud(client):
+    # create
+    nickname = str(uuid.uuid4())
+    r = client.post("/users", json=dict(name=nickname))
+    r.raise_for_status()
+
+    # retrieve
+    url = f"/users/{r.json()['id']}"
+    assert client.get(url).json()["nickname"] == nickname
+
+    # delete
+    client.delete(url).raise_for_status()
+    assert client.get(url).status_code == 404
+

+

Then run the test:

$ poetry run pytest
+=========================== test session starts ===========================
+platform darwin -- Python 3.8.2, pytest-5.4.1, py-1.8.1, pluggy-0.13.1
+rootdir: gino-fastapi-demo
+collected 1 item
+
+tests/test_users.py .                                               [100%]
+
+============================ 1 passed in 1.21s ============================
+

+

Notes for Production¶

Given the popularity of Docker/Kubernetes, we’ll build a Dockerfile for our demo:

FROM python:3.8-alpine as base
+
+FROM base as builder
+RUN apk add --no-cache gcc musl-dev libffi-dev openssl-dev make postgresql-dev
+RUN pip install poetry
+COPY . /src/
+WORKDIR /src
+RUN python -m venv /env && . /env/bin/activate && poetry install
+
+FROM base
+RUN apk add --no-cache postgresql-libs
+COPY --from=builder /env /env
+COPY --from=builder /src /src
+WORKDIR /src
+CMD ["/env/bin/gunicorn", "gino_fastapi_demo.asgi:app", "-b", "0.0.0.0:80", "-k", "uvicorn.workers.UvicornWorker"]
+

+

In this Dockerfile, we used 2 phases to separate the building from the production +image to reduce target artifact size. Also, we are using Gunicorn with +UvicornWorker from Uvicorn as the worker class for best production reliability.

Let’s review what we have in the project.

This is the end of the tutorial to build a demo. Below is an incomplete checklist to +go live:

Set DB_RETRY_LIMIT to a larger number to allow staring the application server +before the database is fully ready.
Implement the same retry logic in migrations/env.py so that Alembic gets the same +functionality.
Enable DB_SSL if needed.
Write a docker-compose.yml for other developers to get a quick taste or even use +it for development.
Enable CI, install pytest-cov and use --cov-fail-under to guarantee coverage.
Integrate static code analysis tools and security/CVE checking tools.
Automate Alembic upgrade properly - e.g. after new version is deployed.
Be aware of the common security attacks like CSRF, XSS, etc.
Write load tests.

Again, the source code of the demo is available here, +and the source of this tutorial is here. +Please feel free to submit PRs to fix issues or add your thoughts. Happy hacking!

+ + +

+ + + +
+ This work is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License. +

+ +

Build a FastAPI Server
+

+ + +

+ +

+ Add your language here. +

+ +

+ +

+ + + + + + + + + + + \ No newline at end of file diff --git a/docs/en/1.0/tutorials/tutorial.html b/docs/en/1.0/tutorials/tutorial.html new file mode 100644 index 0000000..13c47a0 --- /dev/null +++ b/docs/en/1.0/tutorials/tutorial.html @@ -0,0 +1,597 @@ + + + + + + + + GINO Basics - GINO 1.0.2.dev0 documentation + + + + + + + + + + + +

+ +

+ + + + + + + +

+ + + +

+ + HOME + + + CREDITS + + +

Tutorials

How-to Guides

Explanation

Reference

+ +

GINO Basics¶

This tutorial helps beginners to get started with the basic part of GINO. +Target audiences of this tutorial should have basic knowledge of:

RDBMS, especially PostgreSQL
Asynchronous programming in Python

Knowledge of SQLAlchemy is not required.

Introduction¶

Simply speaking, GINO helps you write and execute raw SQL in your asynchronous +application. Instead of interacting RDBMS directly with raw SQL, you can access +your data through friendly objective API.

You may not need GINO, or else to say asynchronous database connection, because +it adds quite some complexity and risk to your stack, and it won’t make your +code run faster, if not slower. Please read Why Asynchronous ORM? for more +information.

Installation¶

To install GINO, run this command in your terminal:

$ pip install gino
+

+

This is the preferred method to install GINO, as it will always install the +most recent stable release.

If you don’t have pip installed, this Python installation guide can guide +you through the process.

Alternatively, if you are using Poetry to manage your project dependencies, +you may want to run:

$ poetry add gino
+

+

Declare Models¶

First of all, we’ll need a Gino object, usually under the +name of db as a global variable:

from gino import Gino
+
+db = Gino()
+

+

db acts like a reference to the database, most database interactions will +go through it.

“Model” is a basic concept in GINO, it is a Python class inherited from +db.Model. Each Model +subclass maps to one table in the database, while each object of the class +represents one row in the table. This must feel familiar if ORM is not a +strange word to you. Now let’s declare a model:

class User(db.Model):
+    __tablename__ = 'users'
+
+    id = db.Column(db.Integer(), primary_key=True)
+    nickname = db.Column(db.Unicode(), default='noname')
+

+

By declaring this User class, we are actually defining a database table +named users, with two columns id and nickname. Note that the fixed +__tablename__ property is required. GINO +suggests singular for model names, and plural for table names. Each +db.Column property defines one column for +the table, where its first parameter indicates the column type in database, +while the rest is for other column attributes or constraints. You can find a +mapping of database types to db types here in the SQLAlchemy +documentation.

Note

SQLAlchemy is a powerful ORM library for non-asynchronous programming in +Python, on top of which GINO is built. SQLAlchemy supports many popular +RDBMS including PostgreSQL and MySQL through different dialect +implementation, so that the same Python code can be compiled into different +SQL depending on the dialect you choose. GINO inherited this support too, +but for now there is only one dialect for PostgreSQL through asyncpg.

If you need constraints or indexes covering multiple columns these are also +defined using properties in model classes. The property names must be unique, +but are otherwise not used. Example:

class Booking(db.Model):
+    __tablename__ = 'bookings'
+
+   day = db.Column(db.Date)
+   booker = db.Column(db.String)
+   room = db.Column(db.String)
+
+   _pk = db.PrimaryKeyConstraint('day', 'booker', name='bookings_pkey')
+   _idx1 = db.Index('bookings_idx_day_room', 'day', 'room', unique=True)
+   _idx2 = db.Index('bookings_idx_booker_room', 'booker', 'room')
+

+

It is also possible to define model constraints and indexes outside the model +class if that is preferred. For more details on constraints and indexes, see +here in the +SQLAlchemy documentation.

Due to implementation limitations it is currently not allowed to specify +explicit constraints and indexes as direct attributes in classes that are meant +to be subclassed. The same is true for constraints and indexes specified +through the __table_args__ attribute. In order +to e.g. define constraints in mixin classes, +declared_attr() is required. Please feel free to read +more about it in its API documentation.

Get Connected¶

The declaration only defined the mapping, it does not create the actual table +in the database. To do that, we need to get connected first. Let’s create a +PostgreSQL database for this tutorial:

$ createdb gino
+

+

Then we tell our db object to connect to this database:

import asyncio
+
+async def main():
+    await db.set_bind('postgresql://localhost/gino')
+
+asyncio.get_event_loop().run_until_complete(main())
+

+

If this runs successfully, then you are connected to the newly created database. +Here postgresql indicates the database dialect to use (the default driver +is asyncpg, you can explicitly specify that with postgresql+asyncpg://, +or simply asyncpg://), localhost is where the server is, and gino +is the name of the database. Check here for more +information about how to compose this database URL.

Note

Under the hood set_bind() calls +create_engine() and bind the engine to this db object. GINO +engine is similar to SQLAlchemy engine, but not identical. Because GINO +engine is asynchronous, while the other is not. Please refer to the API +reference of GINO for more information.

Now that we are connected, let’s create the table in database (in the same +main() method):

await db.gino.create_all()
+

+

Warning

It is db.gino.create_all, +not db.create_all, because +db is inherited from SQLAlchemy MetaData, +and db.create_all is from +SQLAlchemy using non-asynchronous methods, which doesn’t work with the +bound GINO engine.

In practice create_all() is usually +not an ideal solution. To manage database schema, tool like Alembic is +recommended, please see how to Use Alembic.

If you want to explicitly disconnect from the database, you can do this:

await db.pop_bind().close()
+

+

Let’s review the code we have so far together in one piece before moving on:

import asyncio
+from gino import Gino
+
+db = Gino()
+
+
+class User(db.Model):
+    __tablename__ = 'users'
+
+    id = db.Column(db.Integer(), primary_key=True)
+    nickname = db.Column(db.Unicode(), default='noname')
+
+
+async def main():
+    await db.set_bind('postgresql://localhost/gino')
+    await db.gino.create_all()
+
+    # further code goes here
+
+    await db.pop_bind().close()
+
+
+asyncio.get_event_loop().run_until_complete(main())
+

+

CRUD Operations¶

In order to operate on the database, one of GINO’s core features is to Create, +Retrieve, Update or Delete model objects, also known as the CRUD operations.

Create¶

Let’s start by creating a User:

user = await User.create(nickname='fantix')
+# This will cause GINO to execute this SQL with parameter 'fantix':
+# INSERT INTO users (nickname) VALUES ($1) RETURNING users.id, users.nickname
+

+

As mentioned previously, user object represents the newly created row in +the database. You can get the value of each columns by the declared column +properties on the object:

print(f'ID:       {user.id}')           # 1
+print(f'Nickname: {user.nickname}')     # fantix
+

+

It is also possible to create a model instance in-memory first, modify it, then +finally create it in the database:

user = User(nickname='fantix')
+user.nickname += ' (founder)'
+await user.create()
+

+

Retrieve¶

To retrieve a model object from database by primary key, you can use the class +method get() on the model class. Now let’s retrieve +the same row:

user = await User.get(1)
+# SQL (parameter: 1):
+# SELECT users.id, users.nickname FROM users WHERE users.id = $1
+

+

Normal SQL queries are done through a class property +query. For example, let’s retrieve all User +objects from database as a list:

all_users = await db.all(User.query)
+# SQL:
+# SELECT users.id, users.nickname FROM users
+

+

Alternatively, you can use the gino extension on +query. This has exactly the same effect as above:

all_users = await User.query.gino.all()
+# SQL:
+# SELECT users.id, users.nickname FROM users
+

+

Note

User.query is actually a SQLAlchemy query, with its own +non-asynchronous execution methods. GINO added this gino extension on +all executable SQLAlchemy clause objects to conveniently execute them in +the asynchronous way, so that it is even not needed to import the db +reference for execution.

Now let’s add some filters. For example, find all users with ID lower than 10:

founding_users = await User.query.where(User.id < 10).gino.all()
+# SQL (parameter: 10):
+# SELECT users.id, users.nickname FROM users WHERE users.id < $1
+

+

Read more here +about writing queries, because the query object is exactly from SQLAlchemy core.

Warning

Once you get a model object, it is purely in memory and fully detached from +the database. That means, if the row is externally updated, the object +values remain unchanged. Likewise, changes made to the object won’t affect +the database values.

Also, GINO keeps no track of model objects, therefore getting the same row +twice returns two different object with identical values. Modifying one +does not magically affect the other one.

Different than traditional ORMs, the GINO model objects are more like +objective SQL results, rather than stateful ORM objects. In order to adapt +for asynchronous programming, GINO is designed to be that simple. That’s +also why GINO Is Not ORM.

Sometimes we want to get only one object, for example getting the user by name +when logging in. There’s a shortcut for this scenario:

user = await User.query.where(User.nickname == 'fantix').gino.first()
+# SQL (parameter: 'fantix'):
+# SELECT users.id, users.nickname FROM users WHERE users.nickname = $1
+

+

If there is no user named “fantix” in database, user will be None.

And sometimes we may want to get a single value from database, getting the name +of user with ID 1 for example. Then we can use the +select() class method:

name = await User.select('nickname').where(User.id == 1).gino.scalar()
+# SQL (parameter: 1):
+# SELECT users.nickname FROM users WHERE users.id = $1
+print(name)  # fantix
+

+

Or get the count of all users:

population = await db.func.count(User.id).gino.scalar()
+# SQL:
+# SELECT count(users.id) AS count_1 FROM users
+print(population)  # 17 for example
+

+

Update¶

Then let’s try to make some modifications. In this example we’ll mixin some +retrieve operations we just tried.

# create a new user
+user = await User.create(nickname='fantix')
+
+# get its name
+name = await User.select('nickname').where(
+    User.id == user.id).gino.scalar()
+assert name == user.nickname  # they are both 'fantix' before the update
+
+# modification here
+await user.update(nickname='daisy').apply()
+# SQL (parameters: 'daisy', 1):
+# UPDATE users SET nickname=$1 WHERE users.id = $2 RETURNING users.nickname
+print(user.nickname)  # daisy
+
+# get its name again
+name = await User.select('nickname').where(
+    User.id == user.id).gino.scalar()
+print(name)  # daisy
+assert name == user.nickname  # they are both 'daisy' after the update
+

+

So update() is the first GINO method we met so far +on model instance level. It accepts multiple keyword arguments, whose keys are +column names while values are the new value to update to. The following +apply() call makes the update happen in database.

Note

GINO explicitly split the in-memory update and SQL update into two methods: +update() and +apply(). update() +will update the in-memory model object and return an +UpdateRequest object which contains all the +modifications. A following apply() on +UpdateRequest object will apply these recorded +modifications to database by executing a compiled SQL.

Tip

UpdateRequest object has another method named +update() which works the same as the one +on model object, just that it combines the new modifications together with +the ones already recorded in current UpdateRequest +object, and it returns the same UpdateRequest object. +That means, you can chain the updates and end up with one +apply(), or make use of the +UpdateRequest object to combine several updates in a +batch.

update() on model object affects only the row +represented by the object. If you want to do update with wider condition, you +can use the update() on model class level, with a +bit difference:

await User.update.values(nickname='Founding Member ' + User.nickname).where(
+    User.id < 10).gino.status()
+# SQL (parameter: 'Founding Member ', 10):
+# UPDATE users SET nickname=($1 || users.nickname) WHERE users.id < $2
+
+name = await User.select('nickname').where(
+    User.id == 1).gino.scalar()
+print(name)  # Founding Member fantix
+

+

There is no UpdateRequest here, everything is again +SQLAlchemy clause, its +documentation here for +your reference.

Delete¶

At last. Deleting is similar to updating, but way simpler.

user = await User.create(nickname='fantix')
+await user.delete()
+# SQL (parameter: 1):
+# DELETE FROM users WHERE users.id = $1
+print(await User.get(user.id))  # None
+

+

Hint

Remember the model object is in memory? In the last print() +statement, even though the row is already deleted in database, the object +user still exists with its values untouched.

Or mass deletion (never forget the where clause, unless you want to truncate +the whole table!!):

await User.delete.where(User.id > 10).gino.status()
+# SQL (parameter: 10):
+# DELETE FROM users WHERE users.id > $1
+

+

With basic CRUD, you can already make some amazing stuff with +GINO. This tutorial ends here, please find out more in detail from the rest of +this documentation, and have fun hacking!

+ + +

+ + + +
+ This work is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License. +

+ +

GINO Basics
- Introduction
- Installation
- Declare Models
- Get Connected
- CRUD Operations
  - Create
  - Retrieve
  - Update
  - Delete
  +
+

+ + +

+ +

+ Add your language here. +

+ +

+ +

+ + + + + + + + + + + \ No newline at end of file diff --git a/docs/en/1.1b2/.buildinfo b/docs/en/1.1b2/.buildinfo new file mode 100644 index 0000000..5c194fe --- /dev/null +++ b/docs/en/1.1b2/.buildinfo @@ -0,0 +1,4 @@ +# Sphinx build info version 1 +# This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done. +config: ac9737e827b4e8f4942b9648f88dd1d6 +tags: 645f666f9bcd5a90fca523b33c5a78b7 diff --git a/docs/en/1.1b2/_images/263px-Minimum-Tonne.svg.png b/docs/en/1.1b2/_images/263px-Minimum-Tonne.svg.png new file mode 100644 index 0000000..f431e31 Binary files /dev/null and b/docs/en/1.1b2/_images/263px-Minimum-Tonne.svg.png differ diff --git a/docs/en/1.1b2/_images/archlinux.webp b/docs/en/1.1b2/_images/archlinux.webp new file mode 100644 index 0000000..3e358ef Binary files /dev/null and b/docs/en/1.1b2/_images/archlinux.webp differ diff --git a/docs/en/1.1b2/_images/community.svg b/docs/en/1.1b2/_images/community.svg new file mode 100644 index 0000000..dae6507 --- /dev/null +++ b/docs/en/1.1b2/_images/community.svg @@ -0,0 +1,26 @@ + + \ No newline at end of file diff --git a/docs/en/1.1b2/_images/connection.png b/docs/en/1.1b2/_images/connection.png new file mode 100644 index 0000000..e54598d Binary files /dev/null and b/docs/en/1.1b2/_images/connection.png differ diff --git a/docs/en/1.1b2/_images/docs.webp b/docs/en/1.1b2/_images/docs.webp new file mode 100644 index 0000000..20259b1 Binary files /dev/null and b/docs/en/1.1b2/_images/docs.webp differ diff --git a/docs/en/1.1b2/_images/engine.png b/docs/en/1.1b2/_images/engine.png new file mode 100644 index 0000000..6b64561 Binary files /dev/null and b/docs/en/1.1b2/_images/engine.png differ diff --git a/docs/en/1.1b2/_images/exchangeratesapi.webp b/docs/en/1.1b2/_images/exchangeratesapi.webp new file mode 100644 index 0000000..dc2657a Binary files /dev/null and b/docs/en/1.1b2/_images/exchangeratesapi.webp differ diff --git a/docs/en/1.1b2/_images/explanation.svg b/docs/en/1.1b2/_images/explanation.svg new file mode 100644 index 0000000..ef775d1 --- /dev/null +++ b/docs/en/1.1b2/_images/explanation.svg @@ -0,0 +1,19 @@ + + \ No newline at end of file diff --git a/docs/en/1.1b2/_images/gino-fastapi-alembic.svg b/docs/en/1.1b2/_images/gino-fastapi-alembic.svg new file mode 100644 index 0000000..0cfc4b1 --- /dev/null +++ b/docs/en/1.1b2/_images/gino-fastapi-alembic.svg @@ -0,0 +1,3 @@ + + + \ No newline at end of file diff --git a/docs/en/1.1b2/_images/gino-fastapi-config.svg b/docs/en/1.1b2/_images/gino-fastapi-config.svg new file mode 100644 index 0000000..673d084 --- /dev/null +++ b/docs/en/1.1b2/_images/gino-fastapi-config.svg @@ -0,0 +1,3 @@ + + + \ No newline at end of file diff --git a/docs/en/1.1b2/_images/gino-fastapi-env.svg b/docs/en/1.1b2/_images/gino-fastapi-env.svg new file mode 100644 index 0000000..4ec9e4e --- /dev/null +++ b/docs/en/1.1b2/_images/gino-fastapi-env.svg @@ -0,0 +1,3 @@ + + + \ No newline at end of file diff --git a/docs/en/1.1b2/_images/gino-fastapi-layout.svg b/docs/en/1.1b2/_images/gino-fastapi-layout.svg new file mode 100644 index 0000000..07f4701 --- /dev/null +++ b/docs/en/1.1b2/_images/gino-fastapi-layout.svg @@ -0,0 +1,3 @@ + + + \ No newline at end of file diff --git a/docs/en/1.1b2/_images/gino-fastapi-models-users.svg b/docs/en/1.1b2/_images/gino-fastapi-models-users.svg new file mode 100644 index 0000000..886d581 --- /dev/null +++ b/docs/en/1.1b2/_images/gino-fastapi-models-users.svg @@ -0,0 +1,3 @@ + + + \ No newline at end of file diff --git a/docs/en/1.1b2/_images/gino-fastapi-models.svg b/docs/en/1.1b2/_images/gino-fastapi-models.svg new file mode 100644 index 0000000..4dc983c --- /dev/null +++ b/docs/en/1.1b2/_images/gino-fastapi-models.svg @@ -0,0 +1,3 @@ + + + \ No newline at end of file diff --git a/docs/en/1.1b2/_images/gino-fastapi-poetry.svg b/docs/en/1.1b2/_images/gino-fastapi-poetry.svg new file mode 100644 index 0000000..e0da8c1 --- /dev/null +++ b/docs/en/1.1b2/_images/gino-fastapi-poetry.svg @@ -0,0 +1,3 @@ + + + \ No newline at end of file diff --git a/docs/en/1.1b2/_images/gino-fastapi-src.svg b/docs/en/1.1b2/_images/gino-fastapi-src.svg new file mode 100644 index 0000000..7310163 --- /dev/null +++ b/docs/en/1.1b2/_images/gino-fastapi-src.svg @@ -0,0 +1,3 @@ + + + \ No newline at end of file diff --git a/docs/en/1.1b2/_images/gino-fastapi-tests.svg b/docs/en/1.1b2/_images/gino-fastapi-tests.svg new file mode 100644 index 0000000..53673d8 --- /dev/null +++ b/docs/en/1.1b2/_images/gino-fastapi-tests.svg @@ -0,0 +1,3 @@ + + + \ No newline at end of file diff --git a/docs/en/1.1b2/_images/gino-fastapi-views.svg b/docs/en/1.1b2/_images/gino-fastapi-views.svg new file mode 100644 index 0000000..7321a7a --- /dev/null +++ b/docs/en/1.1b2/_images/gino-fastapi-views.svg @@ -0,0 +1,3 @@ + + + \ No newline at end of file diff --git a/docs/en/1.1b2/_images/gino-fastapi.svg b/docs/en/1.1b2/_images/gino-fastapi.svg new file mode 100644 index 0000000..9d365ba --- /dev/null +++ b/docs/en/1.1b2/_images/gino-fastapi.svg @@ -0,0 +1,3 @@ + + + \ No newline at end of file diff --git a/docs/en/1.1b2/_images/github.svg b/docs/en/1.1b2/_images/github.svg new file mode 100644 index 0000000..cb2484b --- /dev/null +++ b/docs/en/1.1b2/_images/github.svg @@ -0,0 +1,27 @@ + + \ No newline at end of file diff --git a/docs/en/1.1b2/_images/happy-hacking.png b/docs/en/1.1b2/_images/happy-hacking.png new file mode 100644 index 0000000..701e7bd Binary files /dev/null and b/docs/en/1.1b2/_images/happy-hacking.png differ diff --git a/docs/en/1.1b2/_images/how-to.svg b/docs/en/1.1b2/_images/how-to.svg new file mode 100644 index 0000000..7461024 --- /dev/null +++ b/docs/en/1.1b2/_images/how-to.svg @@ -0,0 +1,22 @@ + + \ No newline at end of file diff --git a/docs/en/1.1b2/_images/open-source.svg b/docs/en/1.1b2/_images/open-source.svg new file mode 100644 index 0000000..0946f0a --- /dev/null +++ b/docs/en/1.1b2/_images/open-source.svg @@ -0,0 +1,18 @@ + + \ No newline at end of file diff --git a/docs/en/1.1b2/_images/python-gino.webp b/docs/en/1.1b2/_images/python-gino.webp new file mode 100644 index 0000000..f6c11ac Binary files /dev/null and b/docs/en/1.1b2/_images/python-gino.webp differ diff --git a/docs/en/1.1b2/_images/python.svg b/docs/en/1.1b2/_images/python.svg new file mode 100644 index 0000000..f62b29b --- /dev/null +++ b/docs/en/1.1b2/_images/python.svg @@ -0,0 +1,22 @@ + + \ No newline at end of file diff --git a/docs/en/1.1b2/_images/reference.svg b/docs/en/1.1b2/_images/reference.svg new file mode 100644 index 0000000..0c5f656 --- /dev/null +++ b/docs/en/1.1b2/_images/reference.svg @@ -0,0 +1,19 @@ + + \ No newline at end of file diff --git a/docs/en/1.1b2/_images/tutorials.svg b/docs/en/1.1b2/_images/tutorials.svg new file mode 100644 index 0000000..2eb2111 --- /dev/null +++ b/docs/en/1.1b2/_images/tutorials.svg @@ -0,0 +1,26 @@ + + \ No newline at end of file diff --git a/docs/en/1.1b2/_images/why_coroutine.png b/docs/en/1.1b2/_images/why_coroutine.png new file mode 100644 index 0000000..99c743a Binary files /dev/null and b/docs/en/1.1b2/_images/why_coroutine.png differ diff --git a/docs/en/1.1b2/_images/why_multicore.png b/docs/en/1.1b2/_images/why_multicore.png new file mode 100644 index 0000000..c209a9f Binary files /dev/null and b/docs/en/1.1b2/_images/why_multicore.png differ diff --git a/docs/en/1.1b2/_images/why_multithreading.png b/docs/en/1.1b2/_images/why_multithreading.png new file mode 100644 index 0000000..e0e4321 Binary files /dev/null and b/docs/en/1.1b2/_images/why_multithreading.png differ diff --git a/docs/en/1.1b2/_images/why_single_task.png b/docs/en/1.1b2/_images/why_single_task.png new file mode 100644 index 0000000..54fab08 Binary files /dev/null and b/docs/en/1.1b2/_images/why_single_task.png differ diff --git a/docs/en/1.1b2/_images/why_throughput.png b/docs/en/1.1b2/_images/why_throughput.png new file mode 100644 index 0000000..388f533 Binary files /dev/null and b/docs/en/1.1b2/_images/why_throughput.png differ diff --git a/docs/en/1.1b2/_sources/explanation.rst.txt b/docs/en/1.1b2/_sources/explanation.rst.txt new file mode 100644 index 0000000..6d91357 --- /dev/null +++ b/docs/en/1.1b2/_sources/explanation.rst.txt @@ -0,0 +1,7 @@ +Explanation +=========== + +.. toctree:: + :glob: + + explanation/* diff --git a/docs/en/1.1b2/_sources/explanation/async.rst.txt b/docs/en/1.1b2/_sources/explanation/async.rst.txt new file mode 100644 index 0000000..a857170 --- /dev/null +++ b/docs/en/1.1b2/_sources/explanation/async.rst.txt @@ -0,0 +1,214 @@ +Asynchronous Programming 101 +============================ + + +The Story +--------- + +Let's say we want to build a search engine. We'll use a single core computer to +build our index. To make things simpler, our tasks are to fetch web pages +(I/O operation), and process their content (CPU operation). Each task looks +like this: + +.. image:: ../images/why_single_task.png + :align: center + +We have lots of web pages to index, so we simply handle them one by one: + +.. image:: ../images/why_throughput.png + :align: center + +Let's assume the time of each task is constant: each second, 2 tasks are done. +Thus we can say what the throughput of the current system is 2 tasks/sec. How +can we improve the throughput? An obvious answer is to add more CPU cores: + +.. image:: ../images/why_multicore.png + :align: center + +This simply doubles our throughput to 4 tasks/sec, and linearly scales as we +add more CPU cores, if the network is not a bottleneck. But can we improve +the throughput for each CPU core? The answer is yes, we can use +multi-threading: + +.. image:: ../images/why_multithreading.png + :align: center + +Wait a second! The 2 threads barely finished 6 tasks in 2 seconds, a +throughput of only 2.7 tasks/sec, much lower than 4 tasks/sec with 2 cores. +What's wrong with multi-threading? From the diagram we can see: + +* There are yellow bars taking up extra time. +* The green bars can still overlap with any bar in the other thread, but +* non-green bars cannot overlap with non-green bars in the other thread. + +The yellow bars are time taken by `context switches +`_, a necessary part of allowing +multiple threads or processes to run on a single CPU core concurrently. +One CPU core can do only one thing at a time (let's assume a world without +`Hyper-threading `_ or similar), +so in order to run several threads concurrently the CPU must `split its +time `_ into small +slices, and run a little bit of each thread within these slices. The yellow bar +is the overhead for the CPU to switch context to run a different thread. The +scale is a bit dramatic, but it helps with the point. + +Wait again here, the green bars are overlapping between threads. Is the CPU +doing two things at the same time? No, the CPU is doing nothing in the middle +of the green bar, because it's waiting for the HTTP response (I/O). That's how +multi-threading could improve the throughput to 2.7 tasks/sec, instead of +decreasing it to 1.7 tasks/sec. You may try in real to run CPU-intensive +tasks with multi-threading on single core, there won't be any improvement. Like +the multiplexed red bars (in practice there might be more context switches +depending on the task), they appear to be running at the same time, but the +total time for all to finish is actually longer than running the tasks one +by one. That's also why this is called concurrency instead of parallelism. + +As you might imagine, throughput will improve less with each additional thread, +until throughput begins to decrease because context switches are wasting too +much time, not to mention the extra memory footprint taken by new threads. It +is usually not practical to have tens of thousands of threads running on a single +CPU core. How, then, is it possible to have tens of thousands of I/O-bound tasks +running concurrently on a single CPU core? This is the once-famous `C10k +problem `_, usually solved by +asynchronous I/O: + +.. image:: ../images/why_coroutine.png + :align: center + +.. note:: + + Asynchronous I/O and coroutines are two different things, but they usually + go together. Here we will stick with coroutines for simplicity. + +Awesome! The throughput is 3.7 tasks/sec, nearly as good as 4 tasks/sec of 2 +CPU cores. Though this is not real data, compared to OS threads coroutines +do take much less time to context switch and have a lower memory footprint, +thus making them an ideal option for the C10k problem. + + +Cooperative multitasking +------------------------ + +So what is a coroutine? + +In the last diagram above, you may have noticed a difference compared to the +previous diagrams: the green bars are overlapping within the same thread. +That is because the in the last diagram, our code is using asynchronous I/O, +whereas the previously we were using blocking I/O. As the name suggests, blocking +I/O will block the thread until the I/O result is ready. Thus, there can be only +one blocking I/O operation running in a thread at a time. To achieve concurrency +with blocking I/O, either multi-threading or multi-processing must be used. +In contrast, asynchronous I/O allows thousands (or even more) of concurrent +I/O reads and writes within the same thread, with each I/O operation blocking +only the coroutine performing the I/O rather than the whole thread. Like +multi-threading, coroutines provide a means to have concurrency during I/O, +but unlike multi-threading this concurrency occurs within a single thread. + +Threads are scheduled by the operating system using an approach called `preemptive +multitasking `_. For +example, in previous multi-threading diagram there was only one CPU core. When +Thread 2 tried to start processing the first web page content, Thread 1 hadn't +finished processing its own. The OS brutally interrupted Thread 1 and shared +some resource (time) for Thread 2. But Thread 1 also needed CPU time to finish +its processing at the same time, so in turn after a while the OS had to pause +Thread 2 and resume Thread 1. Depending on the size of the task, such turns may +happen several times, so that every thread may have a fair chance to run. It is +something like this: + +.. code-block:: none + + Thread 1: I wanna run! + OS: Okay, here you go... + Thread 2: I wanna run! + OS: Urh, alright one sec ... Thread 1, hold on for a while! + Thread 1: Well I'm not done yet, but you are the boss. + OS: It won't be long. Thread 2 it's your turn now. + Thread 2: Yay! (&%#$@..+*&#) + Thread 1: Can I run now? + OS: Just a moment please ... Thread 2, give it a break! + Thread 2: Alright ... but I really need the CPU. + OS: You'll have it later. Thread 1, hurry up! + +In contrast, coroutines are scheduled by themselves cooperatively with the help +of an event manager. The event manager lives in the same thread as the +coroutines and unlike the OS scheduler that forces context switches on threads, +the event manager acts only when coroutines pause themselves. A thread knows +when it wants to run, but coroutines don't - only the event manager knows which +coroutine should run. The event manager may only trigger the next coroutine to +run after the previous coroutine yields control to wait for an event (e.g. +wait for an HTTP response). This approach to achieve concurrency is called +`cooperative multitasking +`_. It's like this: + +.. code-block:: none + + Coroutine 1: Let me know when event A arrives. I'm done here before that. + Event manager: Okay. What about you, coroutine 2? + Coroutine 2: Um I've got nothing to do here before event B. + Event manager: Cool, I'll be watching. + Event manager: (after a while) Hey coroutine 1, event A is here! + Coroutine 1: Awesome! Let me see ... looks good, but I need event C now. + Event manager: Very well. Seems event B arrived just now, coroutine 2? + Coroutine 2: Oh wonderful! Let me store it in a file ... There! I'm all done. + Event manager: Sweet! Since there's no sign of event C yet, I'll sleep for a while. + (silence) + Event manager: Damn, event C timed out! + Coroutine 1: Arrrrh gotta kill myself with an exception :S + Event manager: Up to you :/ + +For coroutines, a task cannot be paused externally, the task can only pause +itself from within. When there are a lot of coroutines, concurrency depends on +each of them pausing from time to time to wait for events. If you wrote a +coroutine that never paused, it would allow no concurrency at all when running +because no other coroutine would have a chance to run. On the other hand, you +can feel safe in the code between pauses, because no other coroutine can +run at the same time to mess up shared states. That's why in the last diagram, +the red bars are not interleaved like threads. + +.. tip:: + + In Python and asyncio, ``async def`` declares coroutines, ``await`` yields + control to event loop (event manager). + + +Pros and cons +------------- + +Asynchronous I/O may handle tens of thousands of concurrent I/O operations in +the same thread. This can save a lot of CPU time from context switching, and +memory from multi-threading. Therefore if you are dealing with lots of I/O-bound +tasks concurrently, asynchronous I/O can efficiently use limited CPU and memory to +deliver greater throughput. + +With coroutines, you can naturally write sequential code that is cooperatively +scheduled. If your business logic is complex, coroutines could greatly improve +readability of asynchronous I/O code. + +However for a single task, asynchronous I/O can actually impair throughput. For +example, for a simple ``recv()`` operation blocking I/O would just block until +returning the result, but for asynchronous I/O additional steps are required: +register for the read event, wait until event arrives, try to ``recv()``, repeat +until a result returns, and finally feed the result to a callback. With coroutines, +the framework cost is even larger. Thanks to uvloop_ this cost has been minimized +in Python, but it is still additional overhead compared to raw blocking I/O. + +Timing in Asynchronous I/O is also less predictable because of its cooperative +nature. For example, in a coroutine you may want to sleep for 1 second. However, +if another coroutine received control and ran for 2 seconds, by the time we get +back to the first coroutine 2 seconds have already passed. Therefore, ``sleep(1)`` +means to wait for at least 1 second. In practice, you should try your best to make +sure that all code between ``await`` finishes ASAP, being literally cooperative. +Still, there can be code outside your control, so it is important to keep this +unpredictibility of timing in mind. + +Finally, asynchronous programming is complicated. Writing good asynchronous code +is easier said than done, and debugging it is more difficult than debugging +similar synchronous code. Especially when a whole team is working on the +same piece of asynchronous code, it can easily go wrong. Therefore, a general +suggestion is to use asynchronous I/O carefully for I/O-bound high concurrency +scenarios only. It's not a drop-in that will provide a performance boost, but +more like a sharp blade for concurrency with two edges. And if you are dealing with +time-critical tasks, think again to be sure. + + +.. _uvloop: https://github.com/MagicStack/uvloop diff --git a/docs/en/1.1b2/_sources/explanation/engine.rst.txt b/docs/en/1.1b2/_sources/explanation/engine.rst.txt new file mode 100644 index 0000000..ebd59ed --- /dev/null +++ b/docs/en/1.1b2/_sources/explanation/engine.rst.txt @@ -0,0 +1,521 @@ +===================== +Engine and Connection +===================== + +:class:`~gino.engine.GinoEngine` is the core of GINO. It acts like a pool of +connections but also does the work of assembling everyone together: + +.. image:: ../images/engine.png + :align: center + +Under the hood, engine is associated with a specific dialect instance on +creation, e.g. asyncpg dialect. The dialect is actually a set of classes that +implements GINO dialect API, offering all the details about how to operate on +this specific database. In the diagram, gray color means internal, while green +means touchable by end users. + +During creation, the engine will also ask the dialect to create a database +connection pool for it. The pool type is also a part of the dialect API, +because asynchronous database drivers usually have their own pool +implementation, thus their GINO dialects should hide such implementation +differences behind the unified diagram API for engine to use. + +.. note:: + + In SQLAlchemy, database drivers are supposed to follow the DB-API standard, + which does not usually provide a pool implementation. Therefore, SQLAlchemy + has its own pool implementation, created directly in engine. This is where + this diagram doesn't fit SQLAlchemy. + +The pool creates raw connections, not the :class:`~gino.engine.GinoConnection` +green in the diagram. The connection in the diagram is a many-to-one wrapper of +the raw connection, because of the reuse and lazy features, we'll get to that +part later. The connection is created by the engine, thus inherits the same +dialect, and is used for running queries. + +On the outer side, SQLAlchemy queries can be executed directly on the engine or +connection. When on engine, it will try to acquire a reusable connection to +actually execute the connection, and release the connection after use. + +.. note:: + + Another difference to SQLAlchemy here: GINO execution methods always return + final results, while in SQLAlchemy accessing the result may cause further + implicit database accesses. Therefore GINO engine immediately releases the + connection when the execution method on the engine returns, but SQLAlchemy + can only release the connection implicitly when the result data is found + exhausted. + + By immediately releasing a connection, GINO may not release the related raw + connection when the raw connection was reused from another parent + connection. We'll get to this later. + +GINO also supports `implicit execution +`_ +without having to specify an engine or connection explicitly. This is done by +binding the engine to the ``db`` instance, also known as the +:class:`~sqlalchemy.schema.MetaData` or the :class:`~gino.api.Gino` instance. +You may possibly bind a :class:`~gino.engine.GinoConnection` instance, but that +is greatly not recommended because it is very much untested. + +At last, as the ORM / CRUD feature, models are just add-ons on top of +everything else to generate queries. The parent model class is connected to a +``db`` instance on creation, therefore the models can do implicit execution too +if their ``db`` has a bind. + +Then let's get to some details. + + +Creating Engines +---------------- + +GINO reuses the strategy system SQLAlchemy provides to create engines. The name +of GINO's strategy to create asynchronous :class:`~gino.engine.GinoEngine` is +just ``gino``, but only available after ``gino`` is imported:: + + import gino, sqlalchemy + + async def main(): + e = await sqlalchemy.create_engine('postgresql://...', strategy='gino') + # e is a GinoEngine + +.. tip:: + + Please read `this SQLAlchemy document + `_ + to learn about writing database URLs. + +Also the GINO strategy replaces the default driver of dialect ``postgresql://`` +from ``psycopg2`` to ``asyncpg``, so that you don't have to replace the URL +as it may be shared between GINO and vanilla SQLAlchemy in parallel. +Alternatively, you can explicitly specify the driver to use by +``postgresql+asyncpg://...`` or just ``asyncpg://...``. + +GINO also offers a shortcut as :func:`gino.create_engine`, which only sets the +default strategy to ``gino`` and does nothing more. So here is an identical +example:: + + import gino + + async def main(): + e = await gino.create_engine('postgresql://...') + # e is also a GinoEngine + +As you may have noticed, when using the GINO strategy, +:func:`~sqlalchemy.create_engine` returns a coroutine, which must be awaited +for result. Because it will create a database connection pool behind the scene, +and actually making a few initial connections by default. + +For it is just SQLAlchemy :func:`~sqlalchemy.create_engine`, the same rules of +parameters apply in GINO too. Well for now, GINO only supports a small amount +of all the parameters listed in SQLAlchemy document (we are working on it!): + +For Dialect: + +* `isolation_level `_ +* `paramstyle `_ + +For Engine: + +* `echo `_ +* `execution_options `_ +* `logging_name `_ + +While these parameters are discarded by GINO: + +* `module `_ + +In addition, keyword arguments for creating the underlying pool is accepted +here. In the case of asyncpg, they are from :func:`~asyncpg.pool.create_pool`. +For example, we can create an engine without initial connections:: + + e = await gino.create_engine('postgresql://...', min_size=0) + +Similar to SQLAlchemy, GINO also provides shortcut to create engine while +setting it as a bind. In SQLAlchemy it is like this:: + + import sqlalchemy + + metadata = sqlalchemy.MetaData() + metadata.bind = 'postgresql://...' + + # or in short + + metadata = sqlalchemy.MetaData('postgresql://...') + +This implicitly calls :func:`~sqlalchemy.create_engine` under the hood. However +in GINO, creating an engine requires ``await``, it can no longer be hidden +behind a normal assignment statement. Therefore, GINO removed the assignment +magic in subclass :class:`~gino.api.Gino`, reverted it to simple assignment:: + + import gino + + db = gino.Gino() + + async def main(): + # db.bind = 'postgresql://...' doesn't work!! It sets a string on bind + engine = await gino.create_engine('postgresql://...') + db.bind = engine + +And provided a shortcut to do so:: + + engine = await db.set_bind('postgresql://...') + +And another simpler shortcut for one-time usage:: + + db = await gino.Gino('postgresql://...') + +To unset a bind and close the engine:: + + engine, db.bind = db.bind, None + await engine.close() + +Or with a shortcut correspondingly:: + + await engine.pop_bind().close() + +Furthermore, the two steps can be combined into one shortcut with asynchronous +context manager:: + + async with db.with_bind('postgresql://...') as engine: + # your code here + +Managing Connections +-------------------- + +With a :class:`~gino.engine.GinoEngine` at hand, you can acquire connections +from the pool now:: + + conn = await engine.acquire() + +Don't forget to release it after use:: + + await conn.release() + +Yes this can be easily missing. The recommended way is to use the asynchronous +context manager:: + + async with engine.acquire() as conn: + # play with the connection + +Here ``conn`` is a :class:`~gino.engine.GinoConnection` instance. As mentioned +previously, :class:`~gino.engine.GinoConnection` is mapped to an underlying raw +connection, as shown in following diagram: + +.. image:: ../images/connection.png + :align: center + +Each column has at most one actual raw connection, and the number is the +sequence the connections are created in this example. It is designed this way +so that GINO could offer two features for connection management: ``reuse`` and +``lazy``. They are keyword arguments on :meth:`~gino.engine.GinoEngine.acquire` +and by default switched off. + +reuse +""""" + +When acquiring a :class:`~gino.engine.GinoConnection` (2), GINO will borrow a +raw connection (1) from the underlying pool first, and assign it to this +:class:`~gino.engine.GinoConnection` (2). This is the default behavior of +:meth:`~gino.engine.GinoConnection.acquire` with no arguments given. Even when +you are nesting two acquires, you still get two actual raw connection +borrowed:: + + async with engine.acquire() as conn1: + async with engine.acquire() as conn2: + # conn2 is a completely different connection than conn1 + +But sometimes ``conn2`` may exist in a different method:: + + async def outer(): + async with engine.acquire() as conn1: + await inner() + + async def inner(): + async with engine.acquire() as conn2: + # ... + +And we probably wish ``inner`` could reuse the same raw connection in +``outer`` to save some resource, or borrow a new one if ``inner`` is +individually called without ``outer``:: + + async def outer(): + async with engine.acquire() as conn1: + await inner(conn1) + + async def inner(conn2=None): + if conn2 is None: + async with engine.acquire() as conn2: + # ... + else: + # the same ... again + +This is exactly the scenario ``reuse`` could be useful. We can simply tell the +:meth:`~gino.engine.GinoConnection.acquire` to reuse the most recent reusable +connection in current context by setting ``reuse=True``, as presented in this +identical example:: + + async def outer(): + async with engine.acquire() as conn1: + await inner(conn1) + + async def inner(): + async with engine.acquire(reuse=True) as conn2: + # ... + +Back to previous diagram, the blue :class:`~gino.engine.GinoConnection` +instances (3, 4, 6) are "reusing connections" acquired with ``reuse=True``, +while the green ones (2, 5, 7) are not, thus they become "reusable +connections". The green reusable connections are put in a stack in current +context, so that ``acquire(reuse=True)`` always reuses the most recent +connection at the top of the stack. For example, (3) and (4) reuse the only +available (2) at that moment, therefore (2, 3, 4) all map to the same raw +connection (1). Then after (5), (6) no longer reuses (2) because (5) is now the +new head of the stack. + +.. tip:: + + By context, we are actually referring to the context concept in + `contextvars `_ the + new module in Python 3.7, and its partial backport `aiocontextvars + `_. Simply speaking, you may + treat a series of function calls in a chain as in the same context, even if + there is an ``await``. It's something like a thread local in asyncio. + +:class:`~gino.engine.GinoConnection` (2) may be created through +``acquire(reuse=True)`` too - because the stack is empty before (2), there is +nothing to reuse, so (2) upgraded itself to a reusable connection. + +Releasing a reusing connection won't cause the reused raw connection being +returned to the pool, only directly releasing the reused +:class:`~gino.engine.GinoConnection` can do so. Connections should be released +in the reversed order as they are acquired, but if the reused connection is +released before reusing connections by accident, then all the reusing +connections depending on it will turn closed because they are reusing the same +raw connection which is returned to the pool, any further execution will fail. +For example, if (3) is released first, then (2) and (4) are still functional. +But if (2) is released first, then (3) and (4) will be released implicitly and +are no longer usable any more. + +lazy +"""" + +As you may have found, :class:`~gino.engine.GinoConnection` (5) does not have +an underlying raw connection, even when it is reused by (6). This is because +both (5) and (6) set ``lazy=True`` on acquire. + +A lazy connection will not borrow a raw connection on creation, it will only do +so when have to, e.g. when executing a query or starting a transaction. For +example, :class:`~gino.engine.GinoConnection` (7) is acquired lazily without a +raw connection, and (8) is only created when a query is executed on (7):: + + async with engine.acquire(lazy=True) as conn: # (7) + await conn.scalar('select now()') # (8) + +On implementation level, ``lazy`` is extremely easy in +:meth:`~gino.engine.GinoEngine.acquire`: if ``lazy=False`` then borrow a raw +connection, else do nothing. That's it. Before executing a query or starting a +transaction, :class:`~gino.egnine.GinoConnection` will always try to borrow a +raw connection if there is none present. This allows GINO to "transiently +release" a raw connection, while all :class:`~gino.engine.GinoConnection` +mapped to this raw connection are put in lazy mode (again). This is especially +useful before you need to run some networking tasks in a database-related +context - the networking task may take a long time to finish, we don't want to +waste a connection resource checked out for nothing. For example:: + + async with engine.acquire(lazy=True) as conn: # (7) + await conn.scalar('select now()') # (8) + await conn.release(permanent=False) # release (8) + await asyncio.sleep(10) # simulate long I/O work + await conn.scalar('select now()') # re-acquire a new raw connection, + # not necessarily the same (8) + +When used together with ``reuse``, at most one raw connection may be borrowed +for one reusing chain. For example, executing queries on both (5) and (6) will +result only one raw connection checked out, no matter which executes first. It +is also worth noting that, if we set ``lazy=False`` on (6), then the raw +connection will be immediately borrowed on acquire, and shared between both (5) +and (6). It's been quite a while, let me post the same diagram again: + +.. image:: ../images/connection.png + :align: center + + +reusable +"""""""" + +Usually, you don't have to worry about the two options ``reuse`` and ``lazy``, +using the default :meth:`~gino.engine.GinoEngine.acquire` will always create +a concrete :class:`~gino.engine.GinoConnection` with a new raw connection with +it. It is only that they are by default reusable (the green ones). If you need +an absolutely isolated unique connection that has no risk being reused, you may +use ``reusable=False`` on acquire. As shown in the diagram, the unreusable +:class:`~gino.engine.GinoConnection` is an orphan away from any stack:: + + async with engine.acquire(): # (2) + async with engine.acquire(reusable=False): # the unreusable connection + async with engine.acquire(reuse=True): # (3) + +Unreusable connections can be lazy. But it is usually meaningless to specify +both ``reuse=True`` and ``reusable=False`` at the same time, because reusing +connections are always unusable - they are also not in the stack. You cannot +reuse a reusing connection, you only reuse a reusable connection in the stack. +Making a reusing connection unreusable doesn't make its related reusable +connection unreusable. Hmm if this is getting more confusing, just don't use +``acquire(reuse=True, reusable=False)`` unless you know what it does. + + +current_connection +"""""""""""""""""" + +Except for all scenarios supported by above three options, there is still one +left out: we may want to acquire a reusing-only connection. There is no such +option to do so, but GINO could do the same thing through +:attr:`~gino.engine.GinoEngine.current_connection` which is always the reusable +:class:`~gino.engine.GinoConnection` at the top of current stack, or ``None`` +if current stack is empty. + +.. tip:: + + The different between :attr:`~gino.engine.GinoEngine.current_connection` + and :meth:`acquire(reuse=True) ` is, the + latter always produces a :class:`~gino.engine.GinoConnection`, while the + former may not. + + +Executing Queries +----------------- + +Once you have a :class:`~gino.engine.GinoConnection` instance, you can start +executing queries with it. There are 6 variants of the execute method: +:meth:`~gino.engine.GinoConnection.all`, +:meth:`~gino.engine.GinoConnection.first`, +:meth:`~gino.engine.GinoConnection.one`, +:meth:`~gino.engine.GinoConnection.one_or_none`, +:meth:`~gino.engine.GinoConnection.scalar` and +:meth:`~gino.engine.GinoConnection.status`. They are basically the same: +accepting the same parameters, calling the same underlying methods. The +difference is how they treat the results: + +* :meth:`~gino.engine.GinoConnection.all` returns all results in a + :class:`list`, which may be empty when the query has no result, empty but + still a :class:`list`. +* :meth:`~gino.engine.GinoConnection.first` returns the first result directly, + or ``None`` if there is no result at all. There is usually some optimization + behind the scene to efficiently get only the first result, instead of loading + the full result set into memory. +* :meth:`~gino.engine.GinoConnection.one` returns exactly one result. If there + is no result at all or if there are multiple results, an exception is raised. +* :meth:`~gino.engine.GinoConnection.one_or_none` is similar to + :meth:`~gino.engine.GinoConnection.one`, but it returns ``None`` if there is + no result instead or raising an exception. +* :meth:`~gino.engine.GinoConnection.scalar` is similar to + :meth:`~gino.engine.GinoConnection.first`, it returns the first value of the + first result. Quite convenient to just retrieve a scalar value from database, + like ``NOW()``, ``MAX()``, ``COUNT()`` or whatever generates a single value. + ``None`` is also returned when there is no result, it is up to you how to + distinguish no result and the first value is ``NULL``. +* :meth:`~gino.engine.GinoConnection.status` executes the query and discard all + the query results at all. Instead it returns the execution status line as it + is, usually a textual string. Note, there may be no optimization to only + return the status without loading the results, so make your query generate + nothing if you don't want any result. + +By "result", I meant :class:`~sqlalchemy.engine.RowProxy` of SQLAlchemy - an +immutable row instance with both :class:`tuple` and :class:`dict` interfaces. +Database values are translated twice before they are eventually stored in a +:class:`~sqlalchemy.engine.RowProxy`: first by the database driver (dialect) +from network payload to Python objects (see `Type Conversion +`_ of +how asyncpg does this), second by SQLAlchemy +:meth:`~sqlalchemy.types.TypeEngine.result_processor` depending on the actual +type and dialect. + +The arguments taken by these 4 methods are identical to the ones accepted by +SQLAlchemy :meth:`~sqlalchemy.engine.Connection.execute` (click to read more), +usually a plain string of SQL directly or a SQLAlchemy query clause, followed +by query parameters. In the case when multiple dictionaries are given to +``multiparams``, all 4 methods will always return ``None`` discarding all +results. Likewise, the parameter values are processed twice too: first by +:meth:`~sqlalchemy.types.TypeEngine.bind_processor` then the database driver. + +GINO also supports SQLAlchemy +:meth:`~sqlalchemy.engine.Connection.execution_options` provided either on +:meth:`engine level `, +:meth:`connection level ` or on +:meth:`queries `. At +the moment we are working on being compatible with SQLAlchemy execution +options. In the mean while, GINO provides several new execution options, for +example enabling ``return_model`` and providing a ``model`` will make +:meth:`~gino.engine.GinoConnection.all` and +:meth:`~gino.engine.GinoConnection.first` return ORM model instance(s) instead +of :class:`~sqlalchemy.engine.RowProxy` instance(s). See also +:meth:`~sqlalchemy.engine.Connection.execution_options` for more information. + +In addition, GINO has an :meth:`~gino.engine.GinoConnection.iterate` method to +traverse the query results progressively, instead of loading all the results at +once. This method takes the same arguments as the other 4 execute methods do, +and follows the same rule of data handling. For now with asyncpg, this creates +a `server-side cursor +`_. + + +Implicit Execution +------------------ + +Acquire a :class:`~gino.engine.GinoConnection` and execute queries on it, that +is the most explicit way. You can also execute queries on a +:class:`~gino.engine.GinoEngine` instance. In this case, a connection will be +acquired with ``reuse=True`` for you implicitly, and released after returning:: + + await engine.scalar('select now()') + +Equals to:: + + async with engine.acquire(reuse=True) as conn: + await conn.scalar('select now()') + +This allows you to easily write connectionless code. For example:: + + async def get_now(): + return await engine.scalar('select now()') + + async def main(): + async with engine.acquire(): + now = await get_now() + await engine.status('UPDATE ...') + +In this example, ``main()`` will take only one raw connection. ``get_now()`` +can also work alone out of any ``acquire()`` context, thanks to ``reuse``. + +Furthermore, GINO provides the same query APIs on :class:`~gino.api.Gino` +directly. They are simply delegates to corresponding API methods on the +``bind``. This allows even engine-less programming:: + + db = gino.Gino() + + async def get_now(): + return await db.scalar('select now()') + + async def main(): + async with db.with_bind('postgresql://...'): + now = await get_now() + await db.status('UPDATE ...') + +.. note:: + + In this example we didn't put the two queries in an ``acquire()`` block, so + they might be executed in two different connections. + +At last, the SQLAlchemy `implicit execution +`_ +on queries also work in GINO, under an extension named ``gino``:: + + await users_table.select().gino.all() + +By default, the extension :class:`~gino.api.GinoExecutor` is injected on +:class:`~sqlalchemy.sql.expression.Executable` as a property of name ``gino`` +at the creation of :class:`~gino.api.Gino` instance. Therefore, any +:class:`~sqlalchemy.sql.expression.Executable` object has the ``gino`` +property for implicit execution. Similarly, the execution methods calls the +corresponding ones on the ``bind`` of the ``db`` instance. diff --git a/docs/en/1.1b2/_sources/explanation/sa20.rst.txt b/docs/en/1.1b2/_sources/explanation/sa20.rst.txt new file mode 100644 index 0000000..0c18c1f --- /dev/null +++ b/docs/en/1.1b2/_sources/explanation/sa20.rst.txt @@ -0,0 +1,691 @@ +SQLAlchemy 2.0 +============== + +This article explains the new updates from SQLAlchemy 1.4 and 2.0, as well as how GINO +adapts to such changes. + +`SQLAlchemy 2.0 `__ will +deliver many breaking API changes, and `SQLAlchemy 1.4 +`__ will be the "interim" +version for people to eventually upgrade their software to use SQLAlchemy 2.0. + ++-------+------------+----------+----------------------------+ +| GINO | SQLAlchemy | Dialect | Comments | ++=======+============+==========+============================+ +| 1.0.x | 1.3.x | Custom | Current (old-)stable. | ++-------+------------+----------+----------------------------+ +| 1.1.x | 1.3.x | Custom | Next old-stable. | ++-------+------------+----------+----------------------------+ +| 1.2.x | 1.3.x | Custom | Future old-stable (maybe). | ++-------+------------+----------+----------------------------+ +| 1.4.x | 1.4.x | Upstream | 2.0 Interim. | ++-------+------------+----------+----------------------------+ +| 2.0.x | 2.0.x | Upstream | Future stable. | ++-------+------------+----------+----------------------------+ +| 2.1.x | 2.0.x | Upstream | Future stable iterations. | ++-------+------------+----------+----------------------------+ + +To make things easier, GINO will (luckily) also `follow the same versions +`__ for the transition. That is, +GINO 1.4 will be requiring SQLAlchemy 1.4, providing similar pre-1.4-compatible APIs +with deprecations and options to switch to 2.0-API; GINO 2.0 needs SQLAlchemy 2.0 and +provides new APIs only. + +At the same time, GINO 1.1, 1.2 and 1.3 will be reserved as the old-stable versions with +new features added on SQLAlchemy 1.3. And GINO post-2.0 won't match SQLAlchemy versions. + + +The Async Solution +------------------ + +Among all the exciting updates in SQLAlchemy 1.4 / 2.0, `native async support +`__ is the most +significant change for GINO. Simply speaking, SQLAlchemy 1.4 decided to make use of +greenlet_ to mix asynchronous stuff into current code base, avoiding making everything +async. + +Let's say we have an asynchronous method to create an asyncpg connection:: + + import asyncpg + + async def connect(): + return await asyncpg.connect("postgresql:///") + +And an end-user method to use it:: + + async def main(): + conn = await connect() + now = await conn.fetchval("SELECT now()") + +Now instead of directly calling ``connect()`` from ``main()``, I would like to add some +additional logic - let's say, a sanity check:: + + async def safe_connect(): + conn = await connect() + try: + await conn.execute("SELECT 1") + except Exception: + return None + else: + return conn + +Then the end-user should modify ``main()`` to: + +.. code-block:: python + :emphasize-lines: 2,3 + + async def main(): + conn = await safe_connect() + if conn: + now = await conn.fetchval("SELECT now()") + +OK, everything works so far, as they are all regular async code. Here's the interesting +part: ``safe_connect()`` must not be an ``async def`` method. With SQLAlchemy 1.4+, we +could: + +.. code-block:: python + :emphasize-lines: 1,3,4,6,13 + + from sqlalchemy.util import await_only, greenlet_spawn + + def sync_safe_connect(): + conn = await_only(connect()) + try: + await_only(conn.execute("SELECT 1")) + except Exception: + return None + else: + return conn + + async def safe_connect(): + return await greenlet_spawn(sync_safe_connect) + +Behind the scene, ``greenlet_spawn()`` runs the given "sync" method in a greenlet, which +uses ``await_only()`` to switch to the event loop and bridge the underlying async +methods. As ``sync_safe_connect()`` is just a normal Python method, you can imagine how +it works together with lots of other "sync" code asynchronously. + +We're not going deeper into the implementation, but this is basically how SQLAlchemy 1.4 +mixes asyncpg driver into its "sync" code base, and still being able to provide async +APIs on top of them. + + +Async SQLAlchemy +---------------- + +Although greenlet_ might be the only way to practically port SQLAlchemy to the async +world natively without having to maintain 2 copies of the same code, introducing +implicit asynchronous to a large sync code base is still a risky move. + +The sync library existed for years, with many assumptions like using ``threading.Lock`` +to control concurrency. When switching to asynchronous programming, such primitives and +assumptions usually need to be reviewed and probably replaced by e.g. ``asyncio.Lock``. +However, the implicit approach is so convenient that most of the blocking code just +works without any changes at all, lowering the odds to review and find possible issues. + +As a matter of fact, some issues can only be revealed under (heavy) concurrency. For +example, ``threading.Lock.acquire()`` actually works fine in a single coroutine, but `2 +concurrent coroutines `__ +acquiring the same ``threading.Lock`` may easily block the main thread forever. The same +applies to data structures like queues, etc. In short, there must be nothing to block +the main thread. + +Lastly, having implicit asynchronous is a potential maintenance risk. Because the +context switches are usually hidden behind regular sync methods, it is easy to forget +such methods may lead to concurrency issues. Treating coroutines as OS threads is a good +idea and it usually works, but they are fundamentally different. Extra care is always +needed when trying to support both sync and async with the same code base. + +However, such risks are mostly contained within SQLAlchemy itself. End-users are still +using regular explicit asynchronous APIs to leverage the async DB drivers. With proper +reviewing, testing and sufficient community exposure (that's GINO's part), it is still +possible and reliable to have a single SQLAlchemy with 2 sets of APIs (sync + async). +For sure, the APIs are not 100% identical - for example, the ORM lazy-loading won't work +because there is no place for ``await`` in accessing attributes (GINO doesn't like such +implicitness anyways, so yeah). + +To quickly get a picture of async SQLAlchemy (Core), here's a sample from SQLAlchemy:: + + import asyncio + + from sqlalchemy.ext.asyncio import create_async_engine + + async def async_main(): + engine = create_async_engine( + "postgresql+asyncpg://scott:tiger@localhost/test", echo=True, + ) + + async with engine.begin() as conn: + await conn.run_sync(meta.drop_all) + await conn.run_sync(meta.create_all) + + await conn.execute( + t1.insert(), [{"name": "some name 1"}, {"name": "some name 2"}] + ) + + async with engine.connect() as conn: + + # select a Result, which will be delivered with buffered + # results + result = await conn.execute(select(t1).where(t1.c.name == "some name 1")) + + print(result.fetchall()) + + + asyncio.run(async_main()) + + +Auto-Commit Complication +------------------------ + +After using PostgreSQL for a long time, I took many features for granted. The +auto-commit feature is one of them. We all know that ``BEGIN`` starts a transaction and +``COMMIT`` / ``ROLLBACK`` ends it. But what is happening to SQL statements that is not +wrapped in ``BEGIN ... COMMIT`` blocks? + + If you do not issue a ``BEGIN`` command, then each individual statement has an + implicit ``BEGIN`` and (if successful) ``COMMIT`` wrapped around it. + + -- PostgreSQL Documentation, `3.4. Transactions + `__ + +And yes, implicit ``ROLLBACK`` if not successful. This is not directly named as an +"auto-commit" feature, but PostgreSQL does enforce it. Now imagine a database whose +"auto-commit" feature can be turned off - such individual statements are either executed +without ACID-transactions at all (no surprise, there are databases without ACID :doge:), +or the session is left with a open-ended transaction to be further committed. + +`PEP 249 `__ (DB-API 2.0) - the standard for +Python database drivers - was created in such background stories. The assumption it made +appears to me like, the database may probably not support ACID; if it does, auto-commit +is usually not supported. Because it defined only ``commit()`` and ``rollback()`` on a +connection, but no ``begin()``. So I think DB-API assumes that, when executing +statements, the connection is automatically put in a transaction (if ACID is supported), +and you have to call ``commit()`` to persist your changes. Closing a connection will +cause pending transactions rolled back automatically. + + Note that if the database supports an auto-commit feature, this (*the auto-commit + feature -- GINO comments*) must be initially off. + + -- PEP 249 + +As the API behavior is defined, database drivers for even e.g. PostgreSQL with enforced +"auto-commit" has to mimic such behavior. For example, psycopg2_ will automatically emit +a ``BEGIN`` to the database upon the first execution by default, so that such execution +is not auto-committed. The implicit transaction boundary is a very evil thing - people +constantly leaves transactions open (ever seen ``IDLE IN TRANSACTION``?), sometimes even +holding database locks and eventually causing a deadlock storm. + +To work around this workaround, PEP 249 does say: + + An interface method may be provided to turn it (the auto-commit feature) back on. + +So for psycopg2_, one could do this:: + + import psycopg2 + + conn = psycopg2.connect("postgresql:///") + conn.autocommit = True + conn.cursor().execute("SELECT now()") + +Now the database correctly receives this ``SELECT`` statement only, without any implicit +``BEGIN`` surprises. But when we want to have explicit transactions, DB-API only gives +us 2 options: 1) Do it manually:: + + conn.cursor().execute("BEGIN") + conn.cursor().execute("UPDATE ...") + conn.cursor().execute("COMMIT") + +Or 2) turn auto-commit off again:: + + conn.autocommit = False + conn.cursor().execute("UPDATE ...") + conn.commit() + +I know this is frustrating (or maybe people have accepted it), but newer database +drivers like asyncpg_ does provide a cleaner API, by not complying to PEP 249:: + + import asyncpg + + async def main(): + conn = await asyncpg.connect("postgresql://") + + print(await conn.fetchval("SELECT now()")) # SELECT now(); + + async with conn.transaction(): # BEGIN; + await conn.execute("UPDATE ...") # UPDATE ...; + # COMMIT; + +It's much cleaner to see what's actually happening on the wire to the database. This is +also how GINO works. + + +SQLAlchemy for DB-API +--------------------- + +Because SQLAlchemy is built on PEP 249 (DB-API 2.0), its API is also greatly affected by +the PEP standard. For example, imagine what SQL is actually executed by this code:: + + import sqlalchemy as sa + + e = sa.create_engine("postgresql:///", future=True) + with e.connect() as conn: + conn.scalar(sa.text("SELECT now()")) + +Only ``SELECT now()``? No. Here's the answer:: + + with e.connect() as conn: # BEGIN; SELECT version(); ...; ROLLBACK; + conn.scalar(sa.text("SELECT now()")) # BEGIN; SELECT now(); + # ROLLBACK; + +.. note:: + + We are using SQLAlchemy 2.0 API for simplification, by setting ``future=True`` using + SQLAlchemy 1.4. It's way more complicated in SQLAlchemy 1.3 and I don't want to get + into that. + +The reason behind this is, connections have "auto-commit" turned off by default. If +there is no transaction, an implicit ``BEGIN`` will be automatically executed upon the +first statement. This applies to async SQLAlchemy too - even if the underlying asyncpg_ +is not DB-API-compliant, the AsyncpgDialect in SQLAlchemy still wrapped asyncpg_ and +simulated a compatible DB-API. Like this:: + + import sqlalchemy as sa + from sqlalchemy.ext.asyncio import create_async_engine + + async def main(): + e = create_async_engine("postgresql+asyncpg:///") + async with e.connect() as conn: # BEGIN; SELECT version(); ...; ROLLBACK; + await conn.execute(sa.text("SELECT now()")) # BEGIN; SELECT now(); + # ROLLBACK; + +If you want to modify the database permanently, you have to ``commit()`` the implicit +transaction explicitly: + +.. code-block:: python + :emphasize-lines: 5 + + async def main(): + e = ... + async with e.connect() as conn: + await conn.execute(sa.text("UPDATE ...")) # BEGIN; UPDATE ...; + await conn.commit() # COMMIT; + +Or use the explicit transaction API: + +.. code-block:: python + :emphasize-lines: 4,6 + + async def main(): + e = ... + async with e.connect() as conn: + async with conn.begin(): # BEGIN; + await conn.execute(sa.text("UPDATE..")) # UPDATE ...; + # COMMIT; + +Please note that, SQLAlchemy 2.0 doesn't allow soft-nested transactions. In other words, +you cannot nest 2 ``async with conn.begin():`` blocks like this: + +.. code-block:: python + :emphasize-lines: 5 + + async def main(): + e = ... + async with e.connect() as conn: + async with conn.begin(): # BEGIN; + async with conn.begin(): # Error: a transaction is already begun + ... + +This limitation applies to implicit transactions too, even though it's weird: + +.. code-block:: python + :emphasize-lines: 5 + + async def main(): + e = ... + async with e.connect() as conn: + await conn.execute(sa.text("SELECT now()")) # BEGIN; SELECT now(); + async with conn.begin(): # Error: a transaction is already begun + ... + +You have to explicitly close this implicit transaction in order for an explicit +transaction to start successfully: + +.. code-block:: python + :emphasize-lines: 5 + + async def main(): + e = ... + async with e.connect() as conn: + await conn.execute(sa.text("SELECT now()")) # BEGIN; SELECT now(); + await conn.rollback() # ROLLBACK; + async with conn.begin(): # BEGIN; + await conn.execute(sa.text("UPDATE..")) # UPDATE ...; + # COMMIT; + +Similar to Core, SQLAlchemy ORM `follows the same principal +`__. Grab a session, use +it without ``begin()``, and when you want to commit, ``commit()``. Or, use an explicit +transaction in a ``with session.begin():`` block. Personally I don't like that much, but +it is how SQLAlchemy manages transactions. Please follow the link above to read more. + + +SQLAlchemy AUTOCOMMIT +--------------------- + +I know you already miss the WYSIWYG asyncpg_ and GINO API. Hang in there, let's build +GINO 1.4 together with the `SQLAlchemy AUTOCOMMIT feature +`__. + +To turn AUTOCOMMIT back on, we need to set the ``isolation_level`` to ``AUTOCOMMIT`` in +``execution_options``: + +.. code-block:: python + :emphasize-lines: 4,7 + + async def main(): + e = create_async_engine( + "postgresql+asyncpg:///", + execution_options={"isolation_level": "AUTOCOMMIT"}, + ) + async with e.connect() as conn: + await conn.execute(sa.text("SELECT now()")) # SELECT now(); + +Hooray! No more implicit ``BEGIN`` magic. We're one step closer. + +.. note:: + + There is also a keyword argument: + + .. code-block:: python + :emphasize-lines: 3 + + e = create_async_engine( + "postgresql+asyncpg:///", + isolation_level="AUTOCOMMIT", + ) + + But this is implemented very differently than ``execution_options``, and I don't + think it's working for GINO's use case. + +The next question is, how do we explicitly start a transaction? Let's try ``begin()``: + +.. code-block:: python + :emphasize-lines: 5 + + async def main(): + e = ... + async with e.connect() as conn: + await conn.execute(sa.text("SELECT now()")) # SELECT now(); + async with conn.begin(): # Error: a transaction is already begun + ... + +Wait a second ... we've seen this error before! It is the implicit transaction +conflicting with the explicit transaction. But I thought we're in AUTOCOMMIT mode? Even +though the ``isolation_level`` tell the driver not to send ``BEGIN`` to the database, +SQLAlchemy still manages library-level transaction objects. We have to close the virtual +implicit transaction before starting an explicit transaction: + +.. code-block:: python + :emphasize-lines: 5,6 + + async def main(): + e = ... + async with e.connect() as conn: + await conn.execute(sa.text("SELECT now()")) # SELECT now(); + await conn.rollback() # no-op + async with conn.begin(): # no-op + await conn.execute(sa.text("UPDATE..")) # UPDATE ...; + +Well, not quite what we expected. With AUTOCOMMIT set, all of ``begin()``, ``commit()`` +and ``rollback()`` become no-ops. + +Similar to the answers in psycopg2_, we have 2 options here too: 1) manually execute +transaction-control SQLs, or 2) turn off AUTOCOMMIT temporarily. As we want to be more +compatible with SQLAlchemy, let's try 2): + +.. code-block:: python + :emphasize-lines: 6-8 + + async def main(): + e = ... + async with e.connect() as conn: + await conn.execute(sa.text("SELECT now()")) # SELECT now(); + await conn.rollback() # no-op + async with conn.execution_options( + isolation_level="READ COMMITTED" + ).begin(): # BEGIN; + await conn.execute(sa.text("UPDATE..")) # UPDATE ...; + # COMMIT; + +It's working! According to SQLAlchemy docs, ``execution_options()`` creates a shallow +copy of the connection, and apply new values only to the copy. So the original +connection should still be in AUTOCOMMIT, right? Well... + +.. code-block:: python + :emphasize-lines: 11,12 + + async def main(): + e = ... + async with e.connect() as conn: + ... + async with conn.execution_options( + isolation_level="READ COMMITTED" + ).begin(): # BEGIN; + await conn.execute(sa.text("UPDATE..")) # UPDATE ...; + # COMMIT; + + await conn.execute(sa.text("SELECT now()")) # BEGIN; SELECT now(); + # ROLLBACK; + +Unfortunately, the implicit transaction is haunting us again. This is because both the +original connection and its shallow copy points to the same "DB-API" connection (in this +case, a SQLAlchemy wrapper of asyncpg connection), and setting ``isolation_level`` +modifies the value on "DB-API" connection. + +Returning a SQLAlchemy connection back to the pool resets the ``isolation_level`` to its +default value, and acquiring the same connection again will initialize the +``isolation_level`` with values from ``execution_options`` of the engine. But if we want +to keep using the same connection without returning, we have to manually overwrite its +``isolation_level`` again: + +.. code-block:: python + :emphasize-lines: 11 + + async def main(): + e = ... + async with e.connect() as conn: + ... + async with conn.execution_options( + isolation_level="READ COMMITTED" + ).begin(): # BEGIN; + await conn.execute(sa.text("UPDATE..")) # UPDATE ...; + # COMMIT; + + conn.execution_options(isolation_level="AUTOCOMMIT") + await conn.execute(sa.text("SELECT now()")) # SELECT now(); + +Eventually we made it! 🎉 + +Encapsulating all such logic, GINO 1.4 could then provide decent WYSIWYG APIs again:: + + import gino + + async def main(): + engine = await gino.create_engine("postgresql:///") + async with engine.acquire() as conn: + await conn.scalar("SELECT now()") # SELECT now(); + + async with conn.transaction(): # BEGIN; + await conn.status("UPDATE ...") # UPDATE ...; + # COMMIT; + +.. hint:: + + Now I feel that "implementing" auto-commit feature is more like restoring to the + original database behavior, and having auto-commit turned off by default should be + considered as a new feature called "auto-begin" or "implicit transaction". And it's + a bad design introduced in early PEP 249, affecting SQLAlchemy and the ecosystem. + + +Isolation Levels +---------------- + +By far, we only used 2 ``isolation_level`` values: + +* ``AUTOCOMMIT`` +* ``READ COMMITTED`` + +``AUTOCOMMIT`` is not a valid PostgreSQL isolation level. It's only recognized and +consumed by the SQLAlchemy asyncpg dialect to bypass the "auto-begin" simulation. + +``READ COMMITTED`` is the default PostgreSQL isolation level. You can verify this by +executing a SQL directly in a transaction: + +.. code-block:: plpgsql + + # BEGIN; + BEGIN + + # SHOW TRANSACTION ISOLATION LEVEL; + transaction_isolation + ----------------------- + read committed + (1 row) + + # ROLLBACK; + ROLLBACK + +To start a transaction in a different isolation level, you may: + +.. code-block:: plpgsql + :emphasize-lines: 1,7 + + # BEGIN ISOLATION LEVEL SERIALIZABLE; + BEGIN + + # SHOW TRANSACTION ISOLATION LEVEL; + transaction_isolation + ----------------------- + serializable + (1 row) + + # ROLLBACK; + ROLLBACK + +As mentioned earlier, all PostgreSQL statements are executed in a transaction. If no +explicit ``BEGIN`` in place, an implicit transaction is used. So this SQL also works +individually: + +.. code-block:: plpgsql + + # SHOW TRANSACTION ISOLATION LEVEL; + transaction_isolation + ----------------------- + read committed + (1 row) + +But how could we modify the isolation level of such implicit transactions? The answer is +to set isolation level session-wise. This affects all subsequent transactions, including +both implicit and explicit ones, except for explicit transactions with explicit +isolation levels: + +.. code-block:: plpgsql + :emphasize-lines: 1,7,10,16,22,28 + + # SET SESSION CHARACTERISTICS AS TRANSACTION ISOLATION LEVEL SERIALIZABLE; + SET + + # SHOW TRANSACTION ISOLATION LEVEL; + transaction_isolation + ----------------------- + serializable + (1 row) + + # BEGIN; + BEGIN + + # SHOW TRANSACTION ISOLATION LEVEL; + transaction_isolation + ----------------------- + serializable + (1 row) + + # ROLLBACK; + ROLLBACK + + # BEGIN ISOLATION LEVEL READ COMMITTED; + BEGIN + + # SHOW TRANSACTION ISOLATION LEVEL; + transaction_isolation + ----------------------- + read committed + (1 row) + + # ROLLBACK; + ROLLBACK + +Then let's see how SQLAlchemy with asyncpg solves this problem: + +.. code-block:: python + :emphasize-lines: 4,7 + + async def main(): + e = create_async_engine( + "postgresql+asyncpg:///", + execution_options={"isolation_level": "SERIALIZABLE"}, + ) + async with e.connect() as conn: + async with conn.begin(): # BEGIN ISOLATION LEVEL SERIALIZABLE; + await conn.execute(sa.text("UPDATE ...")) # UPDATE ...; + # COMMIT; + +Under the neath, SQLAlchemy is leveraging asyncpg's +``Connection.transaction(isolation="...")`` to set isolation level per transaction. In +GINO, we just need to store the user-defined isolation level, and set before +transactions. + +But there are 2 issues: + +* User-defined isolation level is not applied in PostgreSQL implicit transactions + (a.k.a. auto-commit statements), because no one ``SET SESSION``. +* asyncpg has a bug that ``Connection.transaction(isolation="read_committed")`` always + emit ``BEGIN`` without explicit isolation level, regardless of the actual default + isolation level. + +The asyncpg bug should be fixed from upstream, but we could leverage a session-wide +isolation level setter from base SQLAlchemy dialect for PostgreSQL: + +.. code-block:: python + :emphasize-lines: 13-20,23,24 + + import sqlalchemy as sa + from sqlalchemy import event + from sqlalchemy.dialects.postgresql.base import PGDialect + from sqlalchemy.ext.asyncio import create_async_engine + + + async def main(): + e = create_async_engine( + "postgresql+asyncpg:///", + execution_options={"isolation_level": "AUTOCOMMIT"}, + ) + + def set_isolation_level(dbapi_conn, record): + PGDialect.set_isolation_level( + e.sync_engine.dialect, + dbapi_conn, + "SERIALIZABLE", + ) + + event.listen(e.sync_engine, "connect", set_isolation_level) + + async with e.connect() as conn: + print(await conn.scalar(sa.text("SHOW TRANSACTION ISOLATION LEVEL"))) + # Outputs: serializable + + +.. _greenlet: https://greenlet.readthedocs.io/en/latest/ +.. _psycopg2: https://www.psycopg.org/docs/ +.. _asyncpg: https://github.com/MagicStack/asyncpg diff --git a/docs/en/1.1b2/_sources/explanation/why.rst.txt b/docs/en/1.1b2/_sources/explanation/why.rst.txt new file mode 100644 index 0000000..77455b5 --- /dev/null +++ b/docs/en/1.1b2/_sources/explanation/why.rst.txt @@ -0,0 +1,244 @@ +Why Asynchronous ORM? +===================== + +Conclusion first: in many cases, you don't need to use an asynchronous ORM, or even +asyncio itself. But when you do, it's very important to get it done correctly. + + +When asyncio Helps +------------------ + +As Mike Bayer - the author of SQLAlchemy - `pointed out +`__, even +Python itself can be slower than the database operation in a stereotypical +business-style CRUD-ish application, because the modern databases are so fast when the +query is simple, and this kind of application usually deploys the database in a super +reliable network. In this case, it doesn't make sense to say "Hey I wanna use asyncio +because I love this asynchronous ORM". + +The problem asyncio solves is quite different: when you need to deal with a lot of +concurrent tasks, some of which may block on I/O for arbitrary time, asyncio could +largely leverage the scalability with cooperative multitasking. This is explained in +:doc:`async`. So the ultimate reason to use asyncio should be the application itself, +not the database. + +For example, a chat server may need to talk to tens of thousands of clients at the same +time. The clients are idle for most of the time, because the user didn't send a message +in seconds, which is thousands of times longer than the time needed by the server to +handle the message. Obviously the last thing you want is to have tens of thousands of OS +threads to wait for each of those clients to reply, as it'll disproportionately consume +way too much hardware resource. In contrast, asyncio could easily handle this +concurrency with reasonably tiny overhead. + +.. image:: ../images/263px-Minimum-Tonne.svg.png + :align: right + +Another example is authentication using `OpenID Connect Authorization Code Flow +`__ as a Client. If +the Token Endpoint of the Authorization Server responds fast, everything is fine. But +once it's delayed for even just a few seconds due to unreliable Internet or overloaded +server or whatever reasons, the Client would face a concurrency challenge. According to +`Liebig's law `__, the +minimum throughput of the Client or the Server determines the overall performance. +Comparing to asyncio, it's not wise to use threading model to build the Client and rely +on the Internet which may make the Client the shortest stave. + +Arbitrary delays may happen in the database too. In PostgreSQL, you can |LISTEN|_ to +some asynchronous events that happens unpredictably. Some normal bulk queries may also +take a long time to run, and the database locks can occasionally block too, especially +the dead ones. But these are usually not considered as a high-concurrency scenario, +because the database will possibly hit its bottleneck before your server does, or there +are smarter ways to handle such situations than asyncio. Nevertheless, the database +could be the reason to use asyncio, depending on the actual case. + +In closing, there are scenarios when asyncio could help with concurrency issues. Now +that we know we will write an asynchronous server, then the next question is: + +.. |LISTEN| replace:: ``LISTEN`` +.. _LISTEN: https://www.postgresql.org/docs/current/sql-listen.html + + +How to Access Database +---------------------- + +The first thing to balance here is ORM - how much convenience would you like to +sacrifice for execution performance. As we are talking about ORM, let's assume we need +at least some level of abstraction over raw SQL, or else low-level tools like asyncpg +would be a neat choice. Don't get me wrong - asyncpg is great and convenient to use, but +there won't be such a question "why asynchronous ORM" if we're not seeking an objective +layer over bare SQL. It's totally reasonable and sometimes beneficial and fun to play +with SQL in asynchronous contexts, it's just out of our scope here. + +Because simple queries are executed so fast in the database, one obvious but wrong +approach is to just run the query in the main thread. It won't work because it will 100% +cause a dead lock - not a typical database dead lock, but a hybrid one between the +connection pool and cooperative multitasking. For example, here's a very simple server:: + + import asyncio + from fastapi import FastAPI + from sqlalchemy import create_engine + from sqlalchemy.orm import sessionmaker + + app = FastAPI() + e = create_engine("postgresql://localhost") + Session = sessionmaker(bind=e) + + + @app.get("/") + async def read_root(): + session = Session() + try: + now = session.execute("SELECT now()").scalar() + await asyncio.sleep(0.1) # do some async work + return str(now) + finally: + session.close() + +This follows advices found in :ref:`session_faq_whentocreate` from SQLAlchemy - linking +the **session scope** to the request scope. It works fine within 10 concurrent requests, +but freezes miserably for any number beyond 10: all requests hang and the only way to +stop the server is ``kill -9``. + +What just happened is called a `resource starvation +`__. While the first 10 +requests were waiting for the async work (``sleep(0.1)``), the 11th request came in and +tried to acquire a new database connection from the pool. But the connection pool is +already exhausted (default ``max_overflow=10``) by the first 10 requests, the 11th +request was then blocked by the acquisition. However, this acquisition is unfortunately +a blocking operation, therefore the main thread is blocked and the first 10 requests +lost their chance to finish the async work and return their connection back to the pool +to resume the 11th's acquisition. + +The root cause of such starvation is making asynchronous calls in a **transaction +scope** created implicitly by the default ``autocommit=False``. So other than limiting +the number of concurrent requests down to 10, a more reasonable solution is to avoid +doing asynchronous calls in **transaction scopes** by explicitly ending them:: + + @app.get("/") + async def read_root(): + session = Session() + try: + now = session.execute("SELECT now()").scalar() + session.rollback() # return the connection to avoid starvation + await asyncio.sleep(0.1) # do some async work + return str(now) + finally: + session.close() + +Because of the implicit nature of typical ORMs, it's very hard to identify all such +**transaction scopes** and make sure there's no ``await`` in them - you may have started +an implicit transaction by simply accessing a property like ``current_user.name``. In +practice, it is an impossible mission to correctly mix blocking ORM code with +asynchronous programming in the same thread. So never do this. + +What about thread pool? + +The idea is to defer all blocking code into a thread pool, and run asynchronous +cooperative multitasking in the main thread. This is theoretically possible, but the +same implicit ORM issue keeps haunting us - how do you guarantee there is no blocking +calls in the main thread? Taking one step back, let's assume we could do this cleanly. +What would the code look like? There must be a clear API as the logical separation +between the blocking and asynchronous code - the server executes major DB-free business +logic in the main thread with asynchronous programming, and calls blocking methods for +encapsulated database operations in a thread pool. + +This reminds me of its opposite pattern, where the main server runs in blocking mode, +deferring I/O intensive operations into a task queue like Celery_. Both approaches solve +the problem, the reason to choose one over the other is on the concentration of business +logic - you'd want to write the majority of your code in the main server, and defer only +sub-tasks or low priority operations into a thread pool or task queue. In reality, using +a task queue to e.g. send emails is a more reasonable approach. If you're doing that in +the opposite way, you may want to reconsider the design. + +In summary, other than using raw SQL, the existing typical ORMs could not serve +asynchronous programming well enough. We need true asynchronous ORMs. + +.. _Celery: http://www.celeryproject.org/ + + +Asynchronous ORM Done Right +--------------------------- + +I would describe a proper asynchronous ORM as follows: + + +Don't Starve. +^^^^^^^^^^^^^ + +The very basic requirement for an asynchronous ORM is to avoid resource starvation, at +least avoid the part caused by the ORM design. The fix is actually pretty +straightforward - just make everything ``async``. + +In the example above, if the connection acquisition is asynchronous, it won't block the +main thread any more (it'll block it's own coroutine instead). Therefore, the other +tasks would get a chance to finish the async work and return the connection back to the +pool, thus the starvation is avoided:: + + @app.get("/") + async def read_root(): + async with db.acquire() as conn: # } + async with conn.begin(): # } These two won't block the main thread + now = await db.scalar("SELECT now()") + await asyncio.sleep(0.1) # do some async work + return str(now) + +Even though this code won't cause any resource starvation, using ``await`` within +database transactions is still strongly discouraged, unless it is for the database query +or absolutely necessary. Because after yielding the execution, we have no idea when we +can resume the following execution. That leads to a hanging transaction or at least an +unused database connection for a moment. Doing so won't kill the server immediately, but +it has a few disadvantages: + +1. As the database connection pool is usually much smaller than the asynchronous server + concurrency, this kind of code caps the concurrency down to the DB pool level. +2. Taking a database connection from the pool for nothing is a waste of resource, + especially when the database pool is the shortest stave. +3. Database transactions should be kept short as much as possible. Because long-hanging + transactions may keep certain database locks, leading to performance issues or even + triggering a chain reaction of deadlocks. + + +Be explicit. +^^^^^^^^^^^^ + +With that said, it is especially important to make everything explicit - all the +connection acquisition, transactions and executions. Anything that will block must be +marked with an ``await`` or ``async with``, so that you'll know for sure when a +statement is trying to make any database I/O. Fortunately there's no other way in +asyncio to do this - following `the pattern of Twisted +`__, asyncio is already forcing +explicit ``await`` for any asynchronous operations. + +Being explicit in other part of the ORM design is also useful for enhancing the quality +of users' code. This has nothing to do with asynchronous, it's not a golden standard or +something with a clear cut either. For example: + +* We could design the ORM model instances to be stateless, so that the users don't have + to learn and worry about maintaining the state of the instances. +* There shouldn't be any "buffered operations" which users could "flush" with a single + statement once for all. +* The user should just give direct one-off commands and the ORM executes them right away. +* Also I think the convenience tooling should be well-balanced, the user doesn't have to + guess or remember what an API means - for example, there're more than one ways to load + a many-to-one relationship, I'd prefer to write the query by myself rather than trying + to remember what "join_without_n_plus_1()" means. + + +Be productive. +^^^^^^^^^^^^^^ + +Explicitness and productivity are kind of like two sides of the same coin - more +explicitness means less productive, and more convenience means less explicit. As we are +already using Python, being able to code productively is especially important. For an +asynchronous ORM, is it possible to find a proper balance between the two? + +I think some of the fundamental principals must be explicit, for example the stateless +model and asynchronous yieldings. Then we could add convenient tooling on top of this +foundation as much as it doesn't harm the basic explicitness. The tooling could better +be simple wrappers, grammar sugars or shortcuts for lengthy code, with a proper and +intuitive naming. This is mostly the idea behind GINO's design. + +Additionally, being able to leverage an existing ecosystem is also an important part in +productivity. People could use what they've learned directly, port what they wrote to +the new platform with minimum effort. More importantly - reuse some of the tools from +the ecosystem without having to reinvent the wheel again. diff --git a/docs/en/1.1b2/_sources/how-to.rst.txt b/docs/en/1.1b2/_sources/how-to.rst.txt new file mode 100644 index 0000000..00a13df --- /dev/null +++ b/docs/en/1.1b2/_sources/how-to.rst.txt @@ -0,0 +1,7 @@ +How-to Guides +============= + +.. toctree:: + :glob: + + how-to/* diff --git a/docs/en/1.1b2/_sources/how-to/alembic.rst.txt b/docs/en/1.1b2/_sources/how-to/alembic.rst.txt new file mode 100644 index 0000000..aa60714 --- /dev/null +++ b/docs/en/1.1b2/_sources/how-to/alembic.rst.txt @@ -0,0 +1,135 @@ +Use Alembic +=========== + +Alembic is a lightweight database migration tool for usage with the SQLAlchemy Database +Toolkit for Python. It’s also possible to use with GINO. + +To add migrations to project first of all, add alembic as dependency: + +.. code-block:: console + + $ pip install --user alembic + +When you need to set up alembic for your project. + +Prepare sample project. We will have a structure: + + +.. code-block:: console + + alembic_sample/ + my_app/ + models.py + +Inside ``models.py`` define simple DB Model with GINO: + +.. code-block:: python + + from gino import Gino + + db = Gino() + + class User(db.Model): + __tablename__ = 'users' + + id = db.Column(db.Integer(), primary_key=True) + nickname = db.Column(db.Unicode(), default='noname') + + +Set up Alembic +^^^^^^^^^^^^^^ + +This will need to be done only once. Go to the main folder of your project +``alembic_sample`` and run: + +.. code-block:: console + + $ alembic init alembic + + +Alembic will create a bunch of files and folders in your project directory. One of them +will be ``alembic.ini``. Open ``alembic.ini`` (you can find it in the main project +folder ``alembic_sample``). Now change property ``sqlalchemy.url =`` with your DB +credentials. Like this: + +.. code-block:: ini + + sqlalchemy.url = postgres://{{username}}:{{password}}@{{address}}/{{db_name}} + + +Next go to folder ``alembic/`` and open ``env.py`` file. Inside the ``env.py`` file you +need to import the ``db`` object. In our case ``db`` object is ``db`` from ``models`` +modules. This is a variable that links to your ``Gino()`` instance. + +Inside ``alembic/env.py``:: + + from main_app.models import db + + +And change ``target_metadata =`` to:: + + target_metadata = db + +That’s it. We finished setting up Alembic for a project. + +.. note:: + + All ``alembic`` commands must be run always from the folder that contains the + ``alembic.ini`` file. + + +Create first migration revision +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Same commands you must run each time when you make some changes in DB Models and want to +apply these changes to your DB Schema. + +.. code-block:: console + + $ alembic revision -m "first migration" --autogenerate --head head + +If you have any problems relative to package imports similar to this example: + +.. code-block:: console + + File "alembic/env.py", line 7, in + from main_app.models import db + ModuleNotFoundError: No module named 'main_app' + +Either install your project locally with ``pip install -e .``, ``poetry install`` or +``python setup.py develop``, or add you package to PYTHONPATH, like this: + +.. code-block:: console + + $ export PYTHONPATH=$PYTHONPATH:/full_path/to/alembic_sample + +After the successful run of ``alembic revision`` in folder ``alembic/versions`` you will +see a file with new migration. + + +Apply migration on DB +^^^^^^^^^^^^^^^^^^^^^ + +Now time to apply migration to DB. It will create tables based on you DB Models. + +.. code-block:: console + + $ alembic upgrade head + +Great. Now you apply your first migration. Congratulations! + +Next time, when you will make any changes in DB models just do: + +.. code-block:: console + + $ alembic revision -m "your migration description" --autogenerate --head head + +And + +.. code-block:: console + + alembic upgrade head + + +Full documentation about how to work with Alembic migrations, downgrades and other +things - you can find in official docs https://alembic.sqlalchemy.org diff --git a/docs/en/1.1b2/_sources/how-to/bakery.rst.txt b/docs/en/1.1b2/_sources/how-to/bakery.rst.txt new file mode 100644 index 0000000..2f30075 --- /dev/null +++ b/docs/en/1.1b2/_sources/how-to/bakery.rst.txt @@ -0,0 +1,214 @@ +Bake Queries +============ + +.. versionadded:: 1.1 + +Baked queries are used to boost execution performance for constantly-used queries. +Similar to the :doc:`orm/extensions/baked` in SQLAlchemy, GINO could also cache the +object’s construction and string-compilation steps. Furthermore, GINO automatically +manages a prepared statement for each baked query in every active connection in the +pool. Executing baked queries is at least 40% faster than running normal queries, but +you need to **bake them before creating the engine**. + +GINO provides two approaches for baked queries: + +1. Low-level :class:`~gino.bakery.Bakery` API +2. High-level :meth:`Gino.bake() ` integration + + +Use Bakery with Bare Engine +--------------------------- + +First, we need a bakery:: + + import gino + + bakery = gino.Bakery() + +Then, let's bake some queries:: + + db_time = bakery.bake("SELECT now()") + +Or queries with parameters:: + + user_query = bakery.bake("SELECT * FROM users WHERE id = :uid") + +Let's assume we have this ``users`` table defined in SQLAlchemy Core:: + + import sqlalchemy as sa + + metadata = sa.MetaData() + user_table = sa.Table( + "users", metadata, + sa.Column("id", sa.Integer, primary_key=True), + sa.Column("name", sa.String), + ) + +Now we can bake a similar query with SQLAlchemy Core:: + + user_query = bakery.bake( + sa.select([user_table]).where(user.c.id == sa.bindparam("uid")) + ) + +These baked queries are usually global, and supposed to be shared across the +application. To run them, we need an engine with the bakery:: + + engine = await gino.create_engine("postgresql://localhost/", bakery=bakery) + +By doing so, GINO will bake the queries in the bakery. As new connections are added to +the DB pool, the prepared statements are automatically created behind the scene. + +To execute the baked queries, you could treat the :class:`~gino.bakery.BakedQuery` +instances as if they are the queries themselves, for example:: + + now = await engine.scalar(db_time) + +Pass in parameter values:: + + row = await engine.first(user_query, uid=123) + + +Use the :class:`~gino.api.Gino` Integration +-------------------------------------------- + +In a more common scenario, there will be a :class:`~gino.api.Gino` instance, which has +usually a ``bind`` set - either explicitly or by the Web framework extensions:: + + from gino import Gino + + db = Gino() + + async def main(): + async with db.with_bind("postgresql://localhost/"): + ... + +A :class:`~gino.bakery.Bakery` is automatically created in the ``db`` instance, and fed +to the engine implicitly. You can immediately start to bake queries without further +ado:: + + class User(db.Model): + __tablename__ = "users" + + id = db.Column(db.Integer, primary_key=True) + name = db.Column(db.String) + + db_time = db.bake("SELECT now()") + user_getter = db.bake(User.query.where(User.id == db.bindparam("uid"))) + +And the execution is also simplified with the same ``bind`` magic:: + + async def main(): + async with db.with_bind("postgresql://localhost/"): + print(await db_time.scalar()) + + user: User = await user_getter.first(uid=1) + print(user.name) + +To make things easier, you could even define the baked queries directly on the +model:: + + class User(db.Model): + __tablename__ = "users" + + id = db.Column(db.Integer, primary_key=True) + name = db.Column(db.String) + + @db.bake + def getter(cls): + return cls.query.where(cls.id == db.bindparam("uid")) + + @classmethod + async def get(cls, uid): + return await cls.getter.one_or_none(uid=uid) + +Here GINO treats the ``getter()`` as a :meth:`~gino.declarative.declared_attr` with +``with_table=True``, therefore it takes one positional argument ``cls`` for the ``User`` +class. + + +How to customize loaders? +------------------------- + +If possible, you could bake the additional execution options into the query:: + + user_getter = db.bake( + User.query.where(User.id == db.bindparam("uid")).execution_options( + loader=User.load(comment="Added by loader.") + ) + ) + +The :meth:`~gino.bakery.Bakery.bake` method accepts keyword arguments as execution +options to e.g. simplify the example above into:: + + user_getter = db.bake( + User.query.where(User.id == db.bindparam("uid")), + loader=User.load(comment="Added by loader."), + ) + +If the query construction is complex, :meth:`~gino.bakery.Bakery.bake` could also be +used as a decorator:: + + @db.bake + def user_getter(): + return User.query.where(User.id == db.bindparam("uid")).execution_options( + loader=User.load(comment="Added by loader.") + ) + +Or with short execution options:: + + @db.bake(loader=User.load(comment="Added by loader.")) + def user_getter(): + return User.query.where(User.id == db.bindparam("uid")) + +Meanwhile, it is also possible to override the loader at runtime:: + + user: User = await user_getter.load(User).first(uid=1) + print(user.name) # no more comment on user! + +.. hint:: + + This override won't affect the baked query - it's used only in this execution. + + +What APIs are available on :class:`~gino.bakery.BakedQuery`? +------------------------------------------------------------ + +:class:`~gino.bakery.BakedQuery` is a :class:`~gino.api.GinoExecutor`, so it inherited +all the APIs like :meth:`~gino.api.GinoExecutor.all`, +:meth:`~gino.api.GinoExecutor.first`, :meth:`~gino.api.GinoExecutor.one`, +:meth:`~gino.api.GinoExecutor.one_or_none`, :meth:`~gino.api.GinoExecutor.scalar`, +:meth:`~gino.api.GinoExecutor.status`, :meth:`~gino.api.GinoExecutor.load`, +:meth:`~gino.api.GinoExecutor.timeout`, etc. + +:class:`~gino.api.GinoExecutor` is actually the chained ``.gino`` helper API seen +usually in queries like this:: + + user = await User.query.where(User.id == 123).gino.first() + +So a :class:`~gino.bakery.BakedQuery` can be seen as a normal query with the ``.gino`` +suffix, plus it is directly executable. + +.. seealso:: + + Please see API document of :mod:`gino.bakery` for more information. + + +I don't want the prepared statements. +------------------------------------- + +If you don't need all the baked queries (``m``) to create prepared statements for all +the active database connections (``n``) in the beginning, you could set +``prebake=False`` in the engine initialization to prevent the default initial +``m x n`` prepare calls:: + + e = await gino.create_engine("postgresql://...", bakery=bakery, prebake=False) + +Or if you're using bind:: + + await db.set_bind("postgresql://...", prebake=False) + +This is useful when you're depending on ``db.gino.create_all()`` to create the tables, +because the prepared statements can only be created after the table creation. + +The prepared statements will then be created and cached lazily on demand. + diff --git a/docs/en/1.1b2/_sources/how-to/contributing.rst.txt b/docs/en/1.1b2/_sources/how-to/contributing.rst.txt new file mode 100644 index 0000000..cbab989 --- /dev/null +++ b/docs/en/1.1b2/_sources/how-to/contributing.rst.txt @@ -0,0 +1,152 @@ +.. highlight:: console + +============ +Contributing +============ + +Contributions are welcome, and they are greatly appreciated! Every +little bit helps, and credit will always be given. + +You can contribute in many ways: + +Types of Contributions +---------------------- + +Report Bugs +~~~~~~~~~~~ + +Report bugs at https://github.com/python-gino/gino/issues. + +If you are reporting a bug, please include: + +* Your operating system name and version. +* Any details about your local setup that might be helpful in troubleshooting. +* Detailed steps to reproduce the bug. + +Fix Bugs +~~~~~~~~ + +Look through the GitHub issues for bugs. Anything tagged with "bug" +and "help wanted" is open to whoever wants to implement it. + +Implement Features +~~~~~~~~~~~~~~~~~~ + +Look through the GitHub issues for features. Anything tagged with "enhancement" +and "help wanted" is open to whoever wants to implement it. + +Write Documentation +~~~~~~~~~~~~~~~~~~~ + +GINO could always use more documentation, whether as part of the +official GINO docs, in docstrings, or even on the web in blog posts, +articles, and such. + +Submit Feedback +~~~~~~~~~~~~~~~ + +The best way to send feedback is to file an issue at https://github.com/python-gino/gino/issues. + +If you are proposing a feature: + +* Explain in detail how it would work. +* Keep the scope as narrow as possible, to make it easier to implement. +* Remember that this is a volunteer-driven project, and that contributions + are welcome :) + +Get Started! +------------ + +Ready to contribute? Here's how to set up `gino` for local development. + +1. Fork the `gino` repo on GitHub. +2. Clone your fork locally:: + + $ git clone git@github.com:your_name_here/gino.git + +3. Create a branch for local development:: + + $ cd gino/ + $ git checkout -b name-of-your-bugfix-or-feature + +Now you can make your changes locally. + +4. Create virtual environment. Example for virtualenvwrapper:: + + $ mkvirtualenv gino + +5. Activate the environment and install requirements:: + + $ pip install -r requirements_dev.txt + +6. When you're done making changes, check that your changes pass syntax checks:: + + $ flake8 gino tests + +7. And tests (including other Python versions with tox). +For tests you you will need running database server (see "Tips" section below for configuration details):: + + $ pytest tests + $ tox + +8. For docs run:: + + $ make docs + +It will build and open up docs in your browser. + +9. Commit your changes and push your branch to GitHub:: + + $ git add . + $ git commit -m "Your detailed description of your changes." + $ git push origin name-of-your-bugfix-or-feature + +10. Submit a pull request through the GitHub website. + +Pull Request Guidelines +----------------------- + +Before you submit a pull request, check that it meets these guidelines: + +1. The pull request should include tests. +2. If the pull request adds functionality, the docs should be updated. Put + your new functionality into a function with a docstring, and add the + feature to the list in README.rst. +3. The pull request should work for Python 3.5, 3.6, 3.7 and 3.8. Check + https://github.com/python-gino/gino/actions?query=event%3Apull_request + and make sure that the tests pass for all supported Python versions. + +Tips +---- + +To run a subset of tests:: + +$ py.test -svx tests.test_gino + +By default the tests run against a default installed postgres database. If you +wish to run against a separate database for the tests you can do this by first +creating a new database and user using 'psql' or similar:: + + CREATE ROLE gino WITH LOGIN ENCRYPTED PASSWORD 'gino'; + CREATE DATABASE gino WITH OWNER = gino; + +Then run the tests like so:: + + $ export DB_USER=gino DB_PASS=gino DB_NAME=gino + $ py.test + +Here is an example for db server in docker. Some tests require ssl so you will need to run postgres with ssl enabled. +Terminal 1 (server):: + + $ openssl req -new -text -passout pass:abcd -subj /CN=localhost -out server.req -keyout privkey.pem + $ openssl rsa -in privkey.pem -passin pass:abcd -out server.key + $ openssl req -x509 -in server.req -text -key server.key -out server.crt + $ chmod 600 server.key + $ docker run --name gino_db --rm -it -p 5433:5432 -v "$(pwd)/server.crt:/var/lib/postgresql/server.crt:ro" -v "$(pwd)/server.key:/var/lib/postgresql/server.key:ro" postgres:12-alpine -c ssl=on -c ssl_cert_file=/var/lib/postgresql/server.crt -c ssl_key_file=/var/lib/postgresql/server.key + +Terminal 2 (client):: + + $ export DB_USER=gino DB_PASS=gino DB_NAME=gino DB_PORT=5433 + $ docker exec gino_db psql -U postgres -c "CREATE ROLE $DB_USER WITH LOGIN ENCRYPTED PASSWORD '$DB_PASS'" + $ docker exec gino_db psql -U postgres -c "CREATE DATABASE $DB_NAME WITH OWNER = $DB_USER;" + $ pytest tests/test_aiohttp.py diff --git a/docs/en/1.1b2/_sources/how-to/crud.rst.txt b/docs/en/1.1b2/_sources/how-to/crud.rst.txt new file mode 100644 index 0000000..dd23336 --- /dev/null +++ b/docs/en/1.1b2/_sources/how-to/crud.rst.txt @@ -0,0 +1,5 @@ +==== +CRUD +==== + +**THIS IS A WIP** diff --git a/docs/en/1.1b2/_sources/how-to/faq.rst.txt b/docs/en/1.1b2/_sources/how-to/faq.rst.txt new file mode 100644 index 0000000..73c340a --- /dev/null +++ b/docs/en/1.1b2/_sources/how-to/faq.rst.txt @@ -0,0 +1,389 @@ +Frequently Asked Questions +========================== + +SQLAlchemy 1.4 supports asyncio, what will GINO be? +--------------------------------------------------- + +Starting from 1.4, SQLAlchemy will `support asyncio +`__. +This is a great news to the SQLAlchemy-based ORMs including GINO, because the users will +have one more option, and many GINO hacks can be eventually cleaned up. SQLAlchemy +achieved both sync and async API with the same code base by encapsulating the use of +`greenlet `__. As an "async" user, you don't +need to worry about its internals in most cases, it's fine to just use its async APIs. +Both SQLAlchemy Core and ORM will be async-compatible, but some ORM features that +involve implicit database accesses are disallowed. + +Given such news, GINO no longer has to maintain its own asyncpg dialect for SQLAlchemy +in future versions (yay!). Still, GINO will focus on the differences and keep a +compatible API. To list some of the different/future features: + +* Contextual Connections (see :doc:`../explanation/engine`) +* SQLAlchemy Core-based CRUD models +* The GINO Loader system +* Async MySQL support +* Typing support :sup:`NEW` +* `Trio `__ support :sup:`NEW` +* Execution performance :sup:`NEW` + +As SQLAlchemy async support is considered in Alpha level, GINO will include SQLAlchemy +1.4 support in GINO 2.0.0-alpha.x releases, while the current GINO 1.0.x and 1.1.x will +remain on SQLAlchemy 1.3. GINO 1.x will receive bug fixes and security updates until +both SQLAlchemy async support and GINO 2.x are stabilized. + + +ORM or not ORM? +--------------- + +GINO does perform the Object-Relational Mapping work under the +`Data Mapper Pattern `_, but +it is just not a traditional ORM. The Objects in GINO are completely stateless +from database - they are pure plain Python objects in memory. Changing their +attribute values does not make them "dirty" - or in a different way of thinking +they are always "dirty". Any access to database must be explicitly executed. +Using GINO is more like making up SQL clauses with Models and Objects, +executing them to make changes in database, or loading data from database and +wrapping the results with Objects again. Objects are just row data containers, +you are still dealing with SQL which is represented by Models and SQLAlchemy +core grammars. Besides GINO can be used in a completely `non-ORM way +`__. + + +Can I use features of SQLAlchemy ORM? +------------------------------------- + +SQLAlchemy has `two parts `__: + +* SQLAlchemy Core +* SQLAlchemy ORM + +GINO is built on top of SQLAlchemy Core, so SQLAlchemy ORM won't work in GINO. + + +How to join? +------------ + +GINO invented none about making up queries, everything for that is inherited +from SQLAlchemy. Therefore you just need to know `how to write join in +SQLAlchemy `_. +Especially, `Ádám `_ made some amazing upgrades in +GINO `#113 `_ to make join easier, so +that you can use model classes directly as if they are tables in joining:: + + results = await User.join(Book).select().gino.all() + + +How to connect to database through SSL? +--------------------------------------- + +It depends on the dialect and database driver. For asyncpg, keyword arguments +on :func:`asyncpg.connect() ` are directly +available on :func:`~gino.create_engine` or :meth:`db.set_bind() +`. Therefore, enabling SSL is rather easy:: + + engine = await gino.create_engine(..., ssl=True) + + +What is aiocontextvars and what does it do? +------------------------------------------- + +It is a partial backport of the new built-in module `contextvars +`_ introduced in Python +3.7. In Python 3.5 and 3.6, ``aiocontextvars`` patches ``loop.create_task()`` +to copy context from caller as a workaround to simulate the same behavior. This +is also under discussion in upstream backport project, please read more here: +https://github.com/MagicStack/contextvars/issues/2 + +If you are using Python 3.7, then ``aiocontextvars`` does nothing at all. + +.. note:: + + This answer is for GINO 0.8 and later, please check earlier versions of + this documentation if you are using GINO 0.7. + + +How to define relationships? +---------------------------- + +GINO 1.0 or lower doesn't provide relationship definition feature found in typical ORMs. +However, you could always manually define your tables, design your queries and load the +results explicitly in GINO. Please see :doc:`loaders` for more information. + + +How to define index with multiple columns? +------------------------------------------ + +:: + + class User(db.Model): + __tablename__ = 'users' + + first_name = db.Column(db.Unicode()) + last_name = db.Column(db.Unicode()) + + _name_idx = db.Index('index_on_name', 'first_name', 'last_name') + +The ``_name_idx`` is not used. + + +Is there a django admin interface for GINO? +------------------------------------------- + +Not quite yet, please follow `this discussion +`__. + + +How to use multiple databases for different users on the fly? +------------------------------------------------------------- + +GINO models are linked to a :class:`~gino.api.Gino` instance, while +:class:`~gino.api.Gino` has an optional property ``bind`` to hold a +:class:`~gino.engine.GinoEngine` instance. So when you are executing:: + + user = await User.get(request.user_id) + +The ``bind`` is implicitly used to execute the query. + +In order to use multiple databases, you would need multiple +:class:`~gino.engine.GinoEngine` instances. Here's a full example using FastAPI with +lazy engine creation:: + + from asyncio import Future + from contextvars import ContextVar + + from fastapi import FastAPI, Request + from gino import create_engine + from gino.ext.starlette import Gino + + engines = {} + dbname = ContextVar("dbname") + + + class ContextualGino(Gino): + @property + def bind(self): + e = engines.get(dbname.get("")) + if e and e.done(): + return e.result() + else: + return self._bind + + @bind.setter + def bind(self, val): + self._bind = val + + + app = FastAPI() + db = ContextualGino(app) + + + @app.middleware("http") + async def lazy_engines(request: Request, call_next): + name = request.query_params.get("db", "postgres") + fut = engines.get(name) + if fut is None: + fut = engines[name] = Future() + try: + engine = await create_engine("postgresql://localhost/" + name) + except Exception as e: + fut.set_exception(e) + del engines[name] + raise + else: + fut.set_result(engine) + await fut + dbname.set(name) + return await call_next(request) + + + @app.get("/") + async def get(): + return dict(dbname=await db.scalar("SELECT current_database()")) + + +How to load complex query results? +---------------------------------- + +The API doc of :mod:`gino.loader` explains the available loaders, and there're a few +examples in :doc:`loaders` too. + +Below is an example with a joined result to load both a GINO model and an integer at the +same time, using a :class:`~gino.loader.TupleLoader` with two sub-loaders - +:class:`~gino.loader.ModelLoader` and :class:`~gino.loader.ColumnLoader`:: + + import asyncio + import random + import string + + import gino + from gino.loader import ColumnLoader + + db = gino.Gino() + + + class User(db.Model): + __tablename__ = 'users' + + id = db.Column(db.Integer(), primary_key=True) + name = db.Column(db.Unicode()) + + + class Visit(db.Model): + __tablename__ = 'visits' + + id = db.Column(db.Integer(), primary_key=True) + time = db.Column(db.DateTime(), server_default='now()') + user_id = db.Column(db.ForeignKey('users.id')) + + + async def main(): + async with db.with_bind('postgresql://localhost/gino'): + await db.gino.create_all() + + for i in range(random.randint(5, 10)): + u = await User.create( + name=''.join(random.choices(string.ascii_letters, k=10))) + for v in range(random.randint(10, 20)): + await Visit.create(user_id=u.id) + + visits = db.func.count(Visit.id) + q = db.select([ + User, + visits, + ]).select_from( + User.outerjoin(Visit) + ).group_by( + *User, + ).gino.load((User, ColumnLoader(visits))) + async with db.transaction(): + async for user, visits in q.iterate(): + print(user.name, visits) + + await db.gino.drop_all() + + + asyncio.run(main()) + +Be ware of the :class:`tuple` in ``.gino.load((...))``. + + + +How to do bulk or batch insert / update? +----------------------------------------- + +For a simple example, take a model that has one field, "name." In your application you +have a list of names you would like to add to the database:: + + new_names = ["Austin", "Ali", "Jeff", "Marissa"] + +To quickly insert the names in one query, first construct a dict with the +``{"model_key": "value"}`` format:: + + new_names_dict = [dict(name=new_name) for new_name in new_names] + >> [{'name': 'Austin'}, {'name': 'Ali'}, {'name': 'Jeff'}, {'name': 'Marissa'}] + +Finally, run an insert statement on the model:: + + await User.insert().gino.all(new_names_dict) + + +How to print the executed SQL? +------------------------------ + +GINO uses the same approach from SQLAlchemy: ``create_engine(..., echo=True)``. +(Or ``db.set_bind(..., echo=True)``) Please see also `here +`__. + +If you use any extension, you can also set that in config, by `db_echo` or `DB_ECHO`. + + +How to run ``EXISTS`` SQL? +-------------------------- + +:: + + await db.scalar(db.exists().where(User.email == email).select()) + + +How to work with Alembic? +------------------------- + +The fact that :class:`~gino.api.Gino` is a :class:`~sqlalchemy.schema.MetaData` is the +key to use Alembic. Just import and set ``target_metadata = db`` in Alembic ``env.py`` +will do. See :doc:`alembic` for more details. + + +How to join the same table twice? +--------------------------------- + +This is the same pattern as described in SQLAlchemy :ref:`self_referential`, where you +have a table with "a foreign key reference to itself", or join the same table more than +once, "to represent hierarchical data in flat tables." We'd need to use +:func:`~gino.crud.CRUDModel.alias`, for example:: + + class User(db.Model): + __tablename__ = "users" + + id = db.Column(db.Integer, primary_key=True) + parent_id = db.Column(db.ForeignKey("users.id")) + + Parent = User.alias() + query = User.outerjoin(Parent, User.parent_id == Parent.id).select() + users = await query.gino.load(User.load(parent=Parent)).all() + + +.. _raw-sql: + +How to execute raw SQL with parameters? +--------------------------------------- + +Wrap the SQL with :func:`~sqlalchemy.sql.expression.text`, and use keyword arguments:: + + query = db.text('SELECT * FROM users WHERE id = :id_val') + row = await db.first(query, id_val=1) + +You may even load the rows into model instances:: + + query = query.execution_options(loader=User) + user = await db.first(query, id_val=1) + + +Gino engine is not initialized? +------------------------------- + +GINO models are linked to a :class:`~gino.api.Gino` instance, while +:class:`~gino.api.Gino` has an optional property ``bind`` to hold a +:class:`~gino.engine.GinoEngine` instance. So when you are executing:: + + user = await User.get(request.user_id) + +The ``bind`` is implicitly used to execute the query. If ``bind`` is not set before +this, you'll see this error: + +.. code-block:: text + + gino.exceptions.UninitializedError: Gino engine is not initialized. + +You could use either: + +* Call :meth:`~gino.api.Gino.set_bind` or :meth:`~gino.api.Gino.with_bind` to set the + bind on the :class:`~gino.api.Gino` instance. +* Use one of the Web framework extensions to set the bind for you in usually the server + start-up hook. +* Use explicit ``bind`` for each execution, for example:: + + engine = await create_engine("...") + # ... + user = await User.get(request.user_id, bind=engine) + + +How can I do SQL xxxx in GINO? +------------------------------ + +GINO uses `SQLAlchemy Core `__ queries, so +please check its documentation on how to build queries. The GINO models are simply +wrappers of SQLAlchemy :class:`~sqlalchemy.schema.Table` instances, and the column +attributes on GINO model classes are just SQLAlchemy :class:`~sqlalchemy.schema.Column` +instances, you can use them in building your SQLAlchemy Core queries. + +Alternatively, you could always execute the raw SQL directly, see :ref:`raw-sql` above. diff --git a/docs/en/1.1b2/_sources/how-to/json-props.rst.txt b/docs/en/1.1b2/_sources/how-to/json-props.rst.txt new file mode 100644 index 0000000..45cf95d --- /dev/null +++ b/docs/en/1.1b2/_sources/how-to/json-props.rst.txt @@ -0,0 +1,157 @@ +JSON Property +============= + +GINO provides additional support to leverage native JSON type in the database as +flexible GINO model fields. + +Quick Start +----------- + +:: + + from gino import Gino + from sqlalchemy.dialects.postgresql import JSONB + + db = Gino() + + class User(db.Model): + __tablename__ = "users" + + id = db.Column(db.Integer, primary_key=True) + name = db.Column(db.String) + profile = db.Column(JSONB, nullable=False, server_default="{}") + + age = db.IntegerProperty() + birthday = db.DateTimeProperty() + +The ``age`` and ``birthday`` are JSON properties stored in the ``profile`` column. You +may use them the same way as a normal GINO model field:: + + u = await User.create(name="daisy", age=18) + print(u.name, u.age) # daisy 18 + +.. note:: + + ``profile`` is the default column name for all JSON properties in a model. If you + need a different column name for some JSON properties, you'll need to specify + explicitly:: + + audit_profile = db.Column(JSON, nullable=False, server_default="{}") + + access_log = db.ArrayProperty(prop_name="audit_profile") + abnormal_detected = db.BooleanProperty(prop_name="audit_profile") + +Using JSON properties in queries is supported:: + + await User.query.where(User.age > 16).gino.all() + +This is simply translated into a native JSON query like this: + +.. code-block:: plpgsql + + SELECT users.id, users.name, users.profile + FROM users + WHERE CAST((users.profile ->> $1) AS INTEGER) > $2; -- ('age', 16) + +Datetime type is very much the same:: + + from datetime import datetime + + await User.query.where(User.birthday > datetime(1990, 1, 1)).gino.all() + +And the generated SQL: + +.. code-block:: plpgsql + + SELECT users.id, users.name, users.profile + FROM users + WHERE CAST((users.profile ->> $1) AS TIMESTAMP WITHOUT TIME ZONE) > $2 + -- ('birthday', datetime.datetime(1990, 1, 1, 0, 0)) + +Here's a list of all the supported JSON properties: + ++----------------------------+-----------------------------+-------------+---------------+ +| JSON Property | Python type | JSON type | Database Type | ++============================+=============================+=============+===============+ +| :class:`.StringProperty` | :class:`str` | ``string`` | ``text`` | ++----------------------------+-----------------------------+-------------+---------------+ +| :class:`.IntegerProperty` | :class:`int` | ``number`` | ``int`` | ++----------------------------+-----------------------------+-------------+---------------+ +| :class:`.BooleanProperty` | :class:`bool` | ``boolean`` | ``boolean`` | ++----------------------------+-----------------------------+-------------+---------------+ +| :class:`.DateTimeProperty` | :class:`~datetime.datetime` | ``string`` | ``text`` | ++----------------------------+-----------------------------+-------------+---------------+ +| :class:`.ObjectProperty` | :class:`dict` | ``object`` | JSON | ++----------------------------+-----------------------------+-------------+---------------+ +| :class:`.ArrayProperty` | :class:`list` | ``array`` | JSON | ++----------------------------+-----------------------------+-------------+---------------+ + + +Hooks +----- + +JSON property provides 2 instance-level hooks to customize the data:: + + class User(db.Model): + __tablename__ = "users" + + id = db.Column(db.Integer, primary_key=True) + profile = db.Column(JSONB, nullable=False, server_default="{}") + + age = db.IntegerProperty() + + @age.before_set + def age(self, val): + return val - 1 + + @age.after_get + def age(self, val): + return val + 1 + + u = await User.create(name="daisy", age=18) + print(u.name, u.profile, u.age) # daisy {'age': 17} 18 + +And 1 class-level hook to customize the SQLAlchemy expression of the property:: + + class User(db.Model): + __tablename__ = "users" + + id = db.Column(db.Integer, primary_key=True) + profile = db.Column(JSONB, nullable=False, server_default="{}") + + height = db.JSONProperty() + + @height.expression + def height(cls, exp): + return exp.cast(db.Float) # CAST(profile -> 'height' AS FLOAT) + + +Create Index on JSON Properties +------------------------------- + +We'll need to use :meth:`~gino.declarative.declared_attr` to wait until the model class +is initialized. The rest is very much the same as defining a usual index:: + + class User(db.Model): + __tablename__ = "users" + + id = db.Column(db.Integer, primary_key=True) + profile = db.Column(JSONB, nullable=False, server_default="{}") + + age = db.IntegerProperty() + + @db.declared_attr + def age_idx(cls): + return db.Index("age_idx", cls.age) + +This will lead to the SQL below executed if you run ``db.gino.create_all()``: + +.. code-block:: plpgsql + + CREATE INDEX age_idx ON users (CAST(profile ->> 'age' AS INTEGER)); + +.. warning:: + + Alembic doesn't support auto-generating revisions for functional indexes yet. You'll + need to manually edit the revision. Please follow `this issue + `__ for updates. diff --git a/docs/en/1.1b2/_sources/how-to/loaders.rst.txt b/docs/en/1.1b2/_sources/how-to/loaders.rst.txt new file mode 100644 index 0000000..6d82937 --- /dev/null +++ b/docs/en/1.1b2/_sources/how-to/loaders.rst.txt @@ -0,0 +1,461 @@ +======================== +Loaders and Relationship +======================== + +Loaders are used to load database row results into objects. + +GINO doesn't support automated relationship. We insist explicit code style in +asynchronous programming and that conflicts with some usual ORM relationship +patterns. Instead, GINO provides a rich loader system to assist you with manual +relationships through foreign keys or whatever magic. That means, you are +responsible for writing the queries, and GINO could assemble objects for you +from the database result with loaders you defined. + + +Model Loader +------------ + +The Model Loader is the magic behind GINO CRUD to translate database rows into +model objects. Through CRUD, Model Loaders are assembled internally for you, +you can still use it directly. For example, an ordinary query that returns rows +may look like this:: + + query = db.select([User]) + rows = await query.gino.all() + +In order to load rows into ``User`` objects, you can provide an execution +option ``loader`` with a new :class:`~gino.loader.ModelLoader` instance:: + + from gino.loader import ModelLoader + + query = db.select([User]) + query = query.execution_options(loader=ModelLoader(User)) + users = await query.gino.all() + +The :class:`~gino.loader.ModelLoader` would then load each database row into a +``User`` object. As this is frequently used, GINO made it a shortcut:: + + query = db.select([User]) + query = query.execution_options(loader=User.load()) + users = await query.gino.all() + +And another shortcut:: + + query = db.select([User]) + query = query.execution_options(loader=User) + users = await query.gino.all() + +.. tip:: + + ``User`` as ``loader`` is transformed into ``ModelLoader(User)`` by + :meth:`Loader.get() `, explained later in "Loader + Expression". + +And again:: + + query = db.select([User]) + users = await query.gino.load(User).all() + +This is identical to the normal CRUD query:: + + users = await User.query.gino.all() + + +Loader Expression +----------------- + +So Loaders are actually row post-processors, they define how the database rows +should be processed and returned. Other than :class:`~gino.loader.ModelLoader`, +there're also other loaders that could turn the database rows into different +results like based on your definition. GINO provides the Loader Expression +feature for you to easily assemble complex loaders. + +Here is an example using all loaders at once:: + + uid, user, sep, cols = await db.select([User]).gino.load( + ( + User.id, + User, + '|', + lambda row, ctx: len(row), + ) + ).first() + +Let's check this piece by piece. Overall, the argument of +:meth:`~gino.api.GinoExecutor.load` is a tuple. This is interpreted into a +:class:`~gino.loader.TupleLoader`, with each item of the tuple interpreted as a +Loader Expression recursively. That means, it is possible to nest tuples. The +result of a :class:`~gino.loader.TupleLoader` is a tuple. + +:class:`~sqlalchemy.schema.Column` in Loader Expressions are interpreted as +:class:`~gino.loader.ColumnLoader`. It simply outputs the value of the given +column in the database row. It is your responsibility to select the column in +the query. Please note, :class:`~gino.loader.ColumnLoader` uses the given +column as index to look for the value, not the name of the column. This is a +SQLAlchemy feature to support selecting multiple columns with the same name +from different tables in the same query, especially for ORM. So if you are +using raw textual SQL and wishing to use :class:`~gino.loader.ColumnLoader`, +you'll have to declare columns for the query:: + + now = db.Column('time', db.DateTime()) + result = await db.first(db.text( + 'SELECT now() AT TIME ZONE \'UTC\'' + ).columns( + now, + ).gino.load( + ('now:', now) + ).query) + print(*result) # now: 2018-04-08 08:23:02.431847 + +Let's get back to previous example. The second item in the tuple is a GINO +model class. As we've presented previously, it is interpreted into a +:class:`~gino.loader.ModelLoader`. By default, it loads the values of all the +columns of the give model, and create a new model instance with the values. + +.. tip:: + + For a complex loader expression, the same row is given to all loaders, so + it doesn't matter ``User.id`` is already used before the model loader. + +The last item in the tuple is a callable, it will be called for each row with +two arguments: the first argument is the row itself, while the second is a +contextual value provided by outer loader, we'll get to that later. Similar to +:func:`map`, the return value of the call will be the loaded result. + +At last, if none of the above types matches a Loader Expression, it will be +treated as is. Like the ``'|'`` separator, it will show up as the third item +in every result returned by the query. + + +Many-to-One Relationship +------------------------ + +A classic many-to-one relationship is also known as referencing - the model on +the "many" end keeps a single reference to the model on the "one" end. Although +GINO does not enforce it, usually people use a foreign key for the reference:: + + class Parent(db.Model): + __tablename__ = 'parents' + id = db.Column(db.Integer, primary_key=True) + + class Child(db.Model): + __tablename__ = 'children' + id = db.Column(db.Integer, primary_key=True) + parent_id = db.Column(db.Integer, db.ForeignKey('parents.id')) + +So every child has a single parent (or no parent at all), while one parent may +have multiple children. GINO provides an easy way to load children with their +parents:: + + async for child in Child.load(parent=Parent).gino.iterate(): + print(f'Parent of {child.id} is {child.parent.id}') + +As you may have noticed, ``Child.load`` is exactly the shortcut to create +:class:`~gino.loader.ModelLoader` in the very first example. With some +additional keyword arguments, ``Child.load(parent=Parent)`` is still a +:class:`~gino.loader.ModelLoader` for ``Child``, the model loader is at the +same time a **query builder**. It is identical to do this:: + + async for child in Child.load(parent=Parent).query.gino.iterate(): + print(f'Parent of {child.id} is {child.parent.id}') + +The :attr:`~gino.loader.Loader.query` dynamically generates a SQLAlchemy query +based on the knowledge of the loader, and set the loader as execution option at +the same time. The :class:`~gino.loader.Loader` simply forwarded unknown +attributes to its :attr:`~gino.loader.Loader.query`, that's why ``.query`` can +be omitted. + +For :class:`~gino.loader.ModelLoader`, all keyword arguments are interpreted as +subloaders, their results will be set to the attributes of the result model +under the corresponding keys using :func:`setattr`. For example, ``Parent`` is +interpreted as ``ModelLoader(Parent)`` which loads ``Parent`` instances, and +``Parent`` instances are set as the ``parent`` attribute of the outer ``Child`` +instance. + +.. warning:: + + If multiple children references the same parent, then each child owns a + unique parent instance with identical values. + +.. tip:: + + You don't have to define ``parent`` attribute on ``Child``. But if you do, + you gain the ability to customize how parent is stored or retrieved. For + example, let's store the parent instance as ``_parent``:: + + class Child(db.Model): + __tablename__ = 'children' + id = db.Column(db.Integer, primary_key=True) + parent_id = db.Column(db.Integer, db.ForeignKey('parents.id')) + _parent = None + + @property + def parent(self): + return self._parent + + @parent.setter + def parent(self, value): + self._parent = value + +The query builder works recursively. For :class:`~gino.loader.ModelLoader`, it +uses ``LEFT OUTER JOIN`` to connect the ``FROM`` clauses, in order to achieve +many-to-one scenario. The ``ON`` clause is determined automatically by foreign +keys. You can also customize the ``ON`` clause in case there is no foreign key +(a promise is a promise):: + + loader = Child.load(parent=Parent.on(Child.parent_id == Parent.id)) + async for child in loader.query.gino.iterate(): + print(f'Parent of {child.id} is {child.parent.id}') + +And subloaders can be nested:: + + subloader = Child.load(parent=Parent.on(Child.parent_id == Parent.id)) + loader = Grandson.load(parent=subloader.on(Grandson.parent_id == Child.id)) + +By now, GINO supports only loading many-to-one joined query. To modify a +relationship, just modify the reference column values. + + +Self Referencing +---------------- + +.. warning:: + + Experimental feature. + +Self referencing is usually used to create a tree-like structure. For example:: + + class Category(db.Model): + __tablename__ = 'categories' + id = db.Column(db.Integer, primary_key=True) + parent_id = db.Column(db.Integer, db.ForeignKey('categories.id')) + +In order to load leaf categories with their parents, an alias is needed:: + + Parent = Category.alias() + +Then the query would be something like this:: + + parents = db.select([Category.parent_id]) + query = Category.load(parent=Parent.on( + Category.parent_id == Parent.id + )).where( + ~Category.id.in_(db.select([Category.alias().parent_id])) + ) + async for c in query.gino.iterate(): + print(f'Leaf: {c.id}, Parent: {c.parent.id}') + +The generated SQL looks like this: + +.. code-block:: SQL + + SELECT categories.id, categories.parent_id, categories_1.id, categories_1.parent_id + FROM categories LEFT OUTER JOIN categories AS categories_1 + ON categories.parent_id = categories_1.id + WHERE categories.id NOT IN ( + SELECT categories_2.parent_id + FROM categories AS categories_2 + ) + + +Other Relationships +------------------- + +GINO 0.7.4 introduced an experimental distinct feature to reduce a result set +with loaders, combining rows under specified conditions. This made it possible +to build one-to-many relationships. Using the same parent-child example above, +we could load distinct parents with all their children:: + + class Parent(db.Model): + __tablename__ = 'parents' + id = db.Column(db.Integer, primary_key=True) + + def __init__(self, **kw): + super().__init__(**kw) + self._children = set() + + @property + def children(self): + return self._children + + @children.setter + def add_child(self, child): + self._children.add(child) + + + class Child(db.Model): + __tablename__ = 'children' + id = db.Column(db.Integer, primary_key=True) + parent_id = db.Column(db.Integer, db.ForeignKey('parents.id')) + + + query = Child.outerjoin(Parent).select() + parents = await query.gino.load( + Parent.distinct(Parent.id).load(add_child=Child)).all() + +Here the query is still child outer-joining parent, but the loader is loading +parent instances with distinct IDs only, while storing all their children +through the ``add_child`` setter property. In detail for each row, a parent +instance is firstly loaded if no parent instance with the same ID was loaded +previously, or the same parent instance will be reused. Then a child instance +is loaded from the same row, and fed to the possibly reused parent instance by +``parent.add_child = new_child``. + +Distinct loaders can be nested to load hierarchical data, but it cannot be used +as a query builder to automatically generate queries. + +GINO provides no additional support for one-to-one relationship - the user +should make sure that the query produces rows of distinct instance pairs, and +load them with regular GINO model loaders. When in doubt, the distinct feature +can be used on both sides, but you'll have to manually deal with the conflict +if more than one related instances are found. For example, we could keep only +the last child for each parent:: + + class Parent(db.Model): + __tablename__ = 'parents' + id = db.Column(db.Integer, primary_key=True) + + def __init__(self, **kw): + super().__init__(**kw) + self._child = None + + @property + def child(self): + return self._child + + @child.setter + def child(self, child): + self._child = child + + + class Child(db.Model): + __tablename__ = 'children' + id = db.Column(db.Integer, primary_key=True) + parent_id = db.Column(db.Integer, db.ForeignKey('parents.id')) + + + query = Child.outerjoin(Parent).select() + parents = await query.gino.load( + Parent.distinct(Parent.id).load(child=Child.distinct(Child.id))).all() + + +Similarly, you can build many-to-many relationships in the same way:: + + class Parent(db.Model): + __tablename__ = 'parents' + id = db.Column(db.Integer, primary_key=True) + + def __init__(self, **kw): + super().__init__(**kw) + self._children = set() + + @property + def children(self): + return self._children + + def add_child(self, child): + self._children.add(child) + child._parents.add(self) + + + class Child(db.Model): + __tablename__ = 'children' + id = db.Column(db.Integer, primary_key=True) + + def __init__(self, **kw): + super().__init__(**kw) + self._parents = set() + + @property + def parents(self): + return self._parents + + + class ParentXChild(db.Model): + __tablename__ = 'parents_x_children' + + parent_id = db.Column(db.Integer, db.ForeignKey('parents.id')) + child_id = db.Column(db.Integer, db.ForeignKey('children.id')) + + + query = Parent.outerjoin(ParentXChild).outerjoin(Child).select() + parents = await query.gino.load( + Parent.distinct(Parent.id).load(add_child=Child.distinct(Child.id))).all() + +Likewise, there is for now no way to modify the relationships automatically, +you'll have to manually create, delete or modify ``ParentXChild`` instances. + + +Advanced Usage of Loaders +------------------------- + +You could use combined loaders flexibly in complex queries - loading +relationships is just one special use case. For `example +`_, you could load the count of +visits at the same time of loading each user, by using a tuple loader with two +items - model loader for the user, and column loader for the count:: + + import asyncio + import random + import string + + import gino + from gino.loader import ColumnLoader + + db = gino.Gino() + + + class User(db.Model): + __tablename__ = 'users' + + id = db.Column(db.Integer(), primary_key=True) + name = db.Column(db.Unicode()) + + + class Visit(db.Model): + __tablename__ = 'visits' + + id = db.Column(db.Integer(), primary_key=True) + time = db.Column(db.DateTime(), server_default='now()') + user_id = db.Column(db.ForeignKey('users.id')) + + + async def main(): + async with db.with_bind('postgresql://localhost/gino'): + await db.gino.create_all() + + for i in range(random.randint(5, 10)): + u = await User.create( + name=''.join(random.choices(string.ascii_letters, k=10))) + for v in range(random.randint(10, 20)): + await Visit.create(user_id=u.id) + + visits = db.func.count(Visit.id) + q = db.select([ + User, + visits, + ]).select_from( + User.outerjoin(Visit) + ).group_by( + *User, + ).gino.load((User, ColumnLoader(visits))) + async with db.transaction(): + async for user, visits in q.iterate(): + print(user.name, visits) + + await db.gino.drop_all() + + + asyncio.run(main()) + +Using alias to get ID-ascending pairs from the same table:: + + ua1 = User.alias() + ua2 = User.alias() + join_query = select([ua1, ua2]).where(ua1.id < ua2.id) + loader = ua1.load('id'), ua2.load('id') + result = await join_query.gino.load(loader).all() + print(result) # e.g. [(1, 2), (1, 3), (2, 3)] + +Potentially there could be a lot of different use cases of loaders. We'll add +more inspiration here in the future. diff --git a/docs/en/1.1b2/_sources/how-to/pool.rst.txt b/docs/en/1.1b2/_sources/how-to/pool.rst.txt new file mode 100644 index 0000000..4574ab1 --- /dev/null +++ b/docs/en/1.1b2/_sources/how-to/pool.rst.txt @@ -0,0 +1,27 @@ +=============== +Connection Pool +=============== + +Other than the default connection pool, alternative pools can be used in +their own use cases. +There are options from dialects (currently only +:class:`~gino.dialects.asyncpg.NullPool`), and users can define their own pools. +The base class should be :class:`~gino.dialects.base.Pool`. + +To use non-default pools in raw GINO:: + + from gino.dialects.asyncpg import NullPool + create_engine('postgresql://...', pool_class=NullPool) + +To use non-default pools in extensions (taking Sanic as an example):: + + from gino.dialects.asyncpg import NullPool + from gino.ext.sanic import Gino + + app = sanic.Sanic() + app.config.DB_HOST = 'localhost' + app.config.DB_KWARGS = dict( + pool_class=NullPool, + ) + db = Gino() + db.init_app(app) diff --git a/docs/en/1.1b2/_sources/how-to/schema.rst.txt b/docs/en/1.1b2/_sources/how-to/schema.rst.txt new file mode 100644 index 0000000..c57eaaa --- /dev/null +++ b/docs/en/1.1b2/_sources/how-to/schema.rst.txt @@ -0,0 +1,232 @@ +================== +Schema Declaration +================== + +There are 3 ways to declare your database schema to be used with GINO. Because +GINO is built on top of SQLAlchemy core, either way you are actually declaring +SQLAlchemy :class:`~sqlalchemy.schema.Table`. + + +GINO Engine +----------- + +This is the minimized way to use GINO - using only +:class:`~gino.engine.GinoEngine` (and :class:`~gino.engine.GinoConnection` +too), everything else are vanilla SQLAlchemy core. This is useful when you have +legacy code written in SQLAlchemy core, in need of porting to asyncio. For new +code please use the other two. + +For example, the table declaration is the same as SQLAlchemy core `tutorial +`_:: + + from sqlalchemy import Table, Column, Integer, String, MetaData, ForeignKey + + metadata = MetaData() + + users = Table( + 'users', metadata, + + Column('id', Integer, primary_key=True), + Column('name', String), + Column('fullname', String), + ) + + addresses = Table( + 'addresses', metadata, + + Column('id', Integer, primary_key=True), + Column('user_id', None, ForeignKey('users.id')), + Column('email_address', String, nullable=False) + ) + +.. note:: + + When using GINO Engine only, it is usually your own business to create the + tables with either :meth:`~sqlalchemy.schema.MetaData.create_all` on a + normal non-async SQLAlchemy engine, or using Alembic. However it is still + possible to be done with GINO if it had to:: + + import gino + from gino.schema import GinoSchemaVisitor + + async def main(): + engine = await gino.create_engine('postgresql://...') + await GinoSchemaVisitor(metadata).create_all(engine) + +Then, construct queries, in SQLAlchemy core too:: + + ins = users.insert().values(name='jack', fullname='Jack Jones') + +So far, everything is still in SQLAlchemy. Now let's get connected and execute +the insert:: + + async def main(): + engine = await gino.create_engine('postgresql://localhost/gino') + conn = await engine.acquire() + await conn.status(ins) + print(await conn.all(users.select())) + # Outputs: [(1, 'jack', 'Jack Jones')] + +Here :func:`~gino.create_engine` creates a :class:`~gino.engine.GinoEngine`, +then :meth:`~gino.engine.GinoEngine.acquire` checks out a +:class:`~gino.engine.GinoConnection`, and +:meth:`~gino.engine.GinoConnection.status` executes the insert and returns the +status text. This works similarly as SQLAlchemy +:meth:`~sqlalchemy.engine.Connection.execute` - they take the same parameters +but return a bit differently. There are also other similar query APIs: + +* :meth:`~gino.engine.GinoConnection.all` returns a list of + :class:`~sqlalchemy.engine.RowProxy` +* :meth:`~gino.engine.GinoConnection.first` returns one + :class:`~sqlalchemy.engine.RowProxy`, or ``None`` +* :meth:`~gino.engine.GinoConnection.one` returns one + :class:`~sqlalchemy.engine.RowProxy` +* :meth:`~gino.engine.GinoConnection.one_or_none` returns one + :class:`~sqlalchemy.engine.RowProxy`, or ``None`` +* :meth:`~gino.engine.GinoConnection.scalar` returns a single value, or + ``None`` +* :meth:`~gino.engine.GinoConnection.iterate` returns an asynchronous iterator + which yields :class:`~sqlalchemy.engine.RowProxy` + +Please go to their API for more information. + + +GINO Core +--------- + +In previous scenario, :class:`~gino.engine.GinoEngine` must not be set to +:attr:`metadata.bind ` because it is not a +regular SQLAlchemy Engine thus it won't work correctly. For this, GINO provides +a subclass of :class:`~sqlalchemy.schema.MetaData` as :class:`~gino.api.Gino`, +usually instantiated globally under the name of ``db``. It can be used as a +normal :class:`~sqlalchemy.schema.MetaData` still offering some conveniences: + +* It delegates most public types you can access on ``sqlalchemy`` +* It works with both normal SQLAlchemy engine and asynchronous GINO engine +* It exposes all query APIs on :class:`~gino.engine.GinoConnection` level +* It injects two ``gino`` extensions on SQLAlchemy query clauses and schema + items, allowing short inline execution like ``users.select().gino.all()`` +* It is also the entry for the third scenario, see later + +Then we can achieve previous scenario with less code like this:: + + from gino import Gino + + db = Gino() + + users = db.Table( + 'users', db, + + db.Column('id', db.Integer, primary_key=True), + db.Column('name', db.String), + db.Column('fullname', db.String), + ) + + addresses = db.Table( + 'addresses', db, + + db.Column('id', db.Integer, primary_key=True), + db.Column('user_id', None, db.ForeignKey('users.id')), + db.Column('email_address', db.String, nullable=False) + ) + + async def main(): + async with db.with_bind('postgresql://localhost/gino'): + await db.gino.create_all() + await users.insert().values( + name='jack', + fullname='Jack Jones', + ).gino.status() + print(await users.select().gino.all()) + # Outputs: [(1, 'jack', 'Jack Jones')] + +Similar to SQLAlchemy core and ORM, this is GINO core. All tables and queries +are still made of SQLAlchemy whose rules still apply, but ``sqlalchemy`` seems +never imported. This is useful when ORM is unwanted. + +.. tip:: + + `asyncpgsa `_ does the same thing, + but in a conceptually reversed way - instead of having asyncpg work for + SQLAlchemy, it made SQLAlchemy work for asyncpg (GINO used to be in that + way too because GINO is inspired by asyncpgsa). Either way works fine, it's + just a matter of taste of whose API style to use, SQLAlchemy or asyncpg. + + +GINO ORM +-------- + +If you want to further reduce the length of code, and taking a bit risk of +implicity, welcome to the ORM world. Even though GINO made itself not quite a +traditional ORM by being simple and explict to safely work with asyncio, common +ORM concepts are still valid - a table is a model class, a row is a model +instance. Still the same example rewritten in GINO ORM:: + + from gino import Gino + + db = Gino() + + + class User(db.Model): + __tablename__ = 'users' + + id = db.Column(db.Integer, primary_key=True) + name = db.Column(db.String) + fullname = db.Column(db.String) + + + class Address(db.Model): + __tablename__ = 'addresses' + + id = db.Column(db.Integer, primary_key=True) + user_id = db.Column(None, db.ForeignKey('users.id')) + email_address = db.Column(db.String, nullable=False) + + + async def main(): + async with db.with_bind('postgresql://localhost/gino'): + await db.gino.create_all() + await User.create(name='jack', fullname='Jack Jones') + print(await User.query.gino.all()) + # Outputs: [] + +.. important:: + + The ``__tablename__`` is a mandatory field to define a concrete model. + +As you can see, the declaration is pretty much the same as before. Underlying +they are identical, declaring two tables in ``db``. The ``class`` style is just +more declarative. Instead of ``users.c.name``, you can now access the column by +``User.name``. The implicitly created :class:`~sqlalchemy.schema.Table` is +available at ``User.__table__`` and ``Address.__table__``. You can use anything +that works in GINO core here. + +.. note:: + + Column names can be different as a class property and database column. + For example, name can be declared as + ``nickname = db.Column('name', db.Unicode(), default='noname')``. In this + example, ``User.nickname`` is used to access the column, while in database, + the column name is ``name``. + + What's worth mentioning is where raw SQL statements are used, or + ``TableClause`` is involved, like ``User.insert()``, the original name is + required to be used, because in this case, GINO has no knowledge about the + mappings. + +.. tip:: + + ``db.Model`` is a dynamically created parent class for your models. It is + associated with the ``db`` on initialization, therefore the table is put in + the very ``db`` when you declare your model class. + +Things become different when it comes to CRUD. You can use model level methods +to directly :meth:`~gino.crud.CRUDModel.create` a model instance, instead of +inserting a new row. Or :meth:`~gino.crud.CRUDModel.delete` a model instance +without needing to specify the where clause manually. Query returns model +instances instead of :class:`~sqlalchemy.engine.RowProxy`, and row values are +directly available as attributes on model instances. See also: +:doc:`/how-to/crud`. + +After all, :class:`~gino.engine.GinoEngine` is always in use. Next let's dig +more into it. diff --git a/docs/en/1.1b2/_sources/how-to/transaction.rst.txt b/docs/en/1.1b2/_sources/how-to/transaction.rst.txt new file mode 100644 index 0000000..558a5ae --- /dev/null +++ b/docs/en/1.1b2/_sources/how-to/transaction.rst.txt @@ -0,0 +1,116 @@ +=========== +Transaction +=========== + +It is crucial to correctly manage transactions in an asynchronous program, +because you never know how much time an ``await`` will actually wait for, it +will cause disasters if transactions are on hold for too long. GINO enforces +explicit transaction management to help dealing with it. + + +Basic usage +----------- + +Transactions belong to :class:`~gino.engine.GinoConnection`. The most common +way to use transactions is through an ``async with`` statement:: + + async with connection.transaction() as tx: + await connection.status('INSERT INTO mytable VALUES(1, 2, 3)') + +This guarantees a transaction is opened when entering the ``async with`` block, +and closed when exiting the block - committed if exits normally, or rolled back +by exception. The underlying transaction instance from the database driver is +available at :attr:`~gino.transaction.GinoTransaction.raw_transaction`, but in +most cases you don't need to touch it. + +GINO provides two convenient shortcuts to end the transaction early: + +* :meth:`tx.raise_commit() ` +* :meth:`tx.raise_rollback() ` + +They will raise an internal exception to correspondingly commit or rollback the +transaction, thus the code within the ``async with`` block after +:meth:`~gino.transaction.GinoTransaction.raise_commit` or +:meth:`~gino.transaction.GinoTransaction.raise_rollback` is skipped. The +internal exception is inherited from :exc:`BaseException` so that normal ``try +... except Exception`` block can't trap it. This exception stops propagating at +the end of ``async with`` block, so you don't need to worry about handling it. + +Transactions can also be started on a :class:`~gino.engine.GinoEngine`:: + + async with engine.transaction() as tx: + await engine.status('INSERT INTO mytable VALUES(1, 2, 3)') + +Here a :class:`~gino.engine.GinoConnection` is borrowed implicitly before +entering the transaction, and guaranteed to be returned after transaction is +done. The :class:`~gino.engine.GinoConnection` instance is accessible at +:attr:`tx.connection `. Other than +that, everything else is the same. + +.. important:: + + The implicit connection is by default borrowed with ``reuse=True``. That + means using :meth:`~gino.engine.GinoEngine.transaction` of + :class:`~gino.engine.GinoEngine` within a connection context is the same as + calling :meth:`~gino.engine.GinoConnection.transaction` of the current + connection without having to reference it, no separate connection shall be + created. + +Similarly, if your :class:`~gino.api.Gino` instance has a bind, you may also do +the same on it:: + + async with db.transaction() as tx: + await db.status('INSERT INTO mytable VALUES(1, 2, 3)') + + +Nested Transactions +------------------- + +Transactions can be nested, nested transaction will create a `savepoint +`_ as for +now on asyncpg. A similar example from asyncpg doc:: + + async with connection.transaction() as tx1: + await connection.status('CREATE TABLE mytab (a int)') + + # Create a nested transaction: + async with connection.transaction() as tx2: + await connection.status('INSERT INTO mytab (a) VALUES (1), (2)') + # Rollback the nested transaction: + tx2.raise_rollback() + + # Because the nested transaction was rolled back, there + # will be nothing in `mytab`. + assert await connection.all('SELECT a FROM mytab') == [] + +As you can see, the :meth:`~gino.transaction.GinoTransaction.raise_rollback` +breaks only the ``async with`` block of the specified ``tx2``, the outer +transaction ``tx1`` just continued. What if we break the outer transaction from +within the inner transaction? The inner transaction context won't trap the +internal exception because it recognizes the exception is not created upon +itself. Instead, the inner transaction context only follows the behavior to +either commit or rollback, and lets the exception propagate. + +Because of the default reusing behavior, transactions on engine or ``db`` +follows the same nesting rules. Please see +:class:`~gino.transactions.GinoTransaction` for more information. + + +Manual Control +-------------- + +Other than using ``async with``, you can also manually control the +transaction:: + + tx = await connection.transaction() + try: + await db.status('INSERT INTO mytable VALUES(1, 2, 3)') + await tx.commit() + except Exception: + await tx.rollback() + raise + +You can't use :meth:`~gino.transaction.GinoTransaction.raise_commit` or +:meth:`~gino.transaction.GinoTransaction.raise_rollback` here, similarly it is +prohibited to use :meth:`~gino.transaction.GinoTransaction.commit` and +:meth:`~gino.transaction.GinoTransaction.rollback` in an ``async with`` block. diff --git a/docs/en/1.1b2/_sources/index.rst.txt b/docs/en/1.1b2/_sources/index.rst.txt new file mode 100644 index 0000000..1512377 --- /dev/null +++ b/docs/en/1.1b2/_sources/index.rst.txt @@ -0,0 +1,127 @@ +Welcome to GINO's documentation! +================================ + +.. image:: https://img.shields.io/pypi/v/gino?logo=python&logoColor=white&color=3E6CDE&style=flat-square + :alt: PyPI Release Version + :target: https://pypi.python.org/pypi/gino + +.. image:: https://img.shields.io/github/workflow/status/python-gino/gino/test?label=test&logo=github&color=3E6CDE&style=flat-square + :alt: GitHub Workflow Status for tests + :target: https://github.com/python-gino/gino/actions?query=workflow%3Atest + +.. image:: https://img.shields.io/codacy/coverage/b6a59cdf5ca64eab9104928d4f9bbb97?logo=codacy&color=3E6CDE&style=flat-square + :alt: Codacy coverage + :target: https://app.codacy.com/gh/python-gino/gino/dashboard + +.. image:: https://img.shields.io/badge/Dependabot-active-brightgreen?logo=dependabot&color=3E6CDE&style=flat-square + :target: https://app.dependabot.com/accounts/python-gino/projects/129260 + :alt: Dependabot + + +GINO - GINO Is Not ORM - is a lightweight asynchronous ORM built on top of +SQLAlchemy_ core for Python asyncio_. Now (early 2020) GINO supports only one +dialect asyncpg_. + +.. _asyncio: https://docs.python.org/3/library/asyncio.html +.. _SQLAlchemy: https://www.sqlalchemy.org/ +.. _asyncpg: https://github.com/MagicStack/asyncpg + + +.. cssclass:: boxed-nav + +* .. image:: images/tutorials.svg + + :doc:`tutorials` + + Lessons for the newcomer to get started + +* .. image:: images/how-to.svg + + :doc:`how-to` + + Solve specific problems by steps + +* .. image:: images/explanation.svg + + :doc:`explanation` + + Explains the background and context + +* .. image:: images/reference.svg + + :doc:`reference` + + Describes the software as it is + + +Useful Links +------------ + +.. cssclass:: boxed-nav + +* .. image:: images/github.svg + + `Source Code `_ + + https://github.com/python-gino/gino + +* .. image:: images/community.svg + + `Community `_ + + https://gitter.im/python-gino/Lobby + +* .. image:: images/open-source.svg + + `BSD license `_ + + GINO is free software + +* .. image:: images/python.svg + + `Download `_ + + Download GINO from PyPI + + +.. cssclass:: divio + +Sections by `Divio `_. + +.. toctree:: + :caption: Tutorials + :maxdepth: 1 + :glob: + :hidden: + + tutorials + tutorials/announcement.rst + tutorials/tutorial.rst + tutorials/* + +.. toctree:: + :caption: How-to Guides + :maxdepth: 1 + :glob: + :hidden: + + how-to + how-to/* + +.. toctree:: + :caption: Explanation + :maxdepth: 1 + :glob: + :hidden: + + explanation + explanation/* + +.. toctree:: + :caption: Reference + :maxdepth: 1 + :glob: + :hidden: + + reference + reference/* diff --git a/docs/en/1.1b2/_sources/reference.rst.txt b/docs/en/1.1b2/_sources/reference.rst.txt new file mode 100644 index 0000000..977912b --- /dev/null +++ b/docs/en/1.1b2/_sources/reference.rst.txt @@ -0,0 +1,7 @@ +Reference +========= + +.. toctree:: + :glob: + + reference/* diff --git a/docs/en/1.1b2/_sources/reference/api.rst.txt b/docs/en/1.1b2/_sources/reference/api.rst.txt new file mode 100644 index 0000000..23fc548 --- /dev/null +++ b/docs/en/1.1b2/_sources/reference/api.rst.txt @@ -0,0 +1,6 @@ +API Reference +============= + +.. toctree:: + + api/gino diff --git a/docs/en/1.1b2/_sources/reference/api/gino.aiocontextvars.rst.txt b/docs/en/1.1b2/_sources/reference/api/gino.aiocontextvars.rst.txt new file mode 100644 index 0000000..4728456 --- /dev/null +++ b/docs/en/1.1b2/_sources/reference/api/gino.aiocontextvars.rst.txt @@ -0,0 +1,7 @@ +gino.aiocontextvars module +========================== + +.. automodule:: gino.aiocontextvars + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/en/1.1b2/_sources/reference/api/gino.api.rst.txt b/docs/en/1.1b2/_sources/reference/api/gino.api.rst.txt new file mode 100644 index 0000000..8825a74 --- /dev/null +++ b/docs/en/1.1b2/_sources/reference/api/gino.api.rst.txt @@ -0,0 +1,7 @@ +gino.api module +=============== + +.. automodule:: gino.api + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/en/1.1b2/_sources/reference/api/gino.bakery.rst.txt b/docs/en/1.1b2/_sources/reference/api/gino.bakery.rst.txt new file mode 100644 index 0000000..5762ab7 --- /dev/null +++ b/docs/en/1.1b2/_sources/reference/api/gino.bakery.rst.txt @@ -0,0 +1,7 @@ +gino.bakery module +================== + +.. automodule:: gino.bakery + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/en/1.1b2/_sources/reference/api/gino.crud.rst.txt b/docs/en/1.1b2/_sources/reference/api/gino.crud.rst.txt new file mode 100644 index 0000000..9683c99 --- /dev/null +++ b/docs/en/1.1b2/_sources/reference/api/gino.crud.rst.txt @@ -0,0 +1,7 @@ +gino.crud module +================ + +.. automodule:: gino.crud + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/en/1.1b2/_sources/reference/api/gino.declarative.rst.txt b/docs/en/1.1b2/_sources/reference/api/gino.declarative.rst.txt new file mode 100644 index 0000000..8ec0bdd --- /dev/null +++ b/docs/en/1.1b2/_sources/reference/api/gino.declarative.rst.txt @@ -0,0 +1,7 @@ +gino.declarative module +======================= + +.. automodule:: gino.declarative + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/en/1.1b2/_sources/reference/api/gino.dialects.aiomysql.rst.txt b/docs/en/1.1b2/_sources/reference/api/gino.dialects.aiomysql.rst.txt new file mode 100644 index 0000000..338ccc5 --- /dev/null +++ b/docs/en/1.1b2/_sources/reference/api/gino.dialects.aiomysql.rst.txt @@ -0,0 +1,7 @@ +gino.dialects.aiomysql module +============================= + +.. automodule:: gino.dialects.aiomysql + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/en/1.1b2/_sources/reference/api/gino.dialects.asyncpg.rst.txt b/docs/en/1.1b2/_sources/reference/api/gino.dialects.asyncpg.rst.txt new file mode 100644 index 0000000..9423016 --- /dev/null +++ b/docs/en/1.1b2/_sources/reference/api/gino.dialects.asyncpg.rst.txt @@ -0,0 +1,7 @@ +gino.dialects.asyncpg module +============================ + +.. automodule:: gino.dialects.asyncpg + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/en/1.1b2/_sources/reference/api/gino.dialects.base.rst.txt b/docs/en/1.1b2/_sources/reference/api/gino.dialects.base.rst.txt new file mode 100644 index 0000000..c512657 --- /dev/null +++ b/docs/en/1.1b2/_sources/reference/api/gino.dialects.base.rst.txt @@ -0,0 +1,7 @@ +gino.dialects.base module +========================= + +.. automodule:: gino.dialects.base + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/en/1.1b2/_sources/reference/api/gino.dialects.rst.txt b/docs/en/1.1b2/_sources/reference/api/gino.dialects.rst.txt new file mode 100644 index 0000000..5366ba2 --- /dev/null +++ b/docs/en/1.1b2/_sources/reference/api/gino.dialects.rst.txt @@ -0,0 +1,20 @@ +gino.dialects package +===================== + +Submodules +---------- + +.. toctree:: + :maxdepth: 4 + + gino.dialects.aiomysql + gino.dialects.asyncpg + gino.dialects.base + +Module contents +--------------- + +.. automodule:: gino.dialects + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/en/1.1b2/_sources/reference/api/gino.engine.rst.txt b/docs/en/1.1b2/_sources/reference/api/gino.engine.rst.txt new file mode 100644 index 0000000..0075c29 --- /dev/null +++ b/docs/en/1.1b2/_sources/reference/api/gino.engine.rst.txt @@ -0,0 +1,7 @@ +gino.engine module +================== + +.. automodule:: gino.engine + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/en/1.1b2/_sources/reference/api/gino.exceptions.rst.txt b/docs/en/1.1b2/_sources/reference/api/gino.exceptions.rst.txt new file mode 100644 index 0000000..d3659da --- /dev/null +++ b/docs/en/1.1b2/_sources/reference/api/gino.exceptions.rst.txt @@ -0,0 +1,7 @@ +gino.exceptions module +====================== + +.. automodule:: gino.exceptions + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/en/1.1b2/_sources/reference/api/gino.ext.rst.txt b/docs/en/1.1b2/_sources/reference/api/gino.ext.rst.txt new file mode 100644 index 0000000..fe56088 --- /dev/null +++ b/docs/en/1.1b2/_sources/reference/api/gino.ext.rst.txt @@ -0,0 +1,10 @@ +gino.ext package +================ + +Module contents +--------------- + +.. automodule:: gino.ext + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/en/1.1b2/_sources/reference/api/gino.json_support.rst.txt b/docs/en/1.1b2/_sources/reference/api/gino.json_support.rst.txt new file mode 100644 index 0000000..5a7c069 --- /dev/null +++ b/docs/en/1.1b2/_sources/reference/api/gino.json_support.rst.txt @@ -0,0 +1,7 @@ +gino.json\_support module +========================= + +.. automodule:: gino.json_support + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/en/1.1b2/_sources/reference/api/gino.loader.rst.txt b/docs/en/1.1b2/_sources/reference/api/gino.loader.rst.txt new file mode 100644 index 0000000..06ce463 --- /dev/null +++ b/docs/en/1.1b2/_sources/reference/api/gino.loader.rst.txt @@ -0,0 +1,7 @@ +gino.loader module +================== + +.. automodule:: gino.loader + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/en/1.1b2/_sources/reference/api/gino.rst.txt b/docs/en/1.1b2/_sources/reference/api/gino.rst.txt new file mode 100644 index 0000000..b507d15 --- /dev/null +++ b/docs/en/1.1b2/_sources/reference/api/gino.rst.txt @@ -0,0 +1,38 @@ +gino package +============ + +Subpackages +----------- + +.. toctree:: + :maxdepth: 4 + + gino.dialects + gino.ext + +Submodules +---------- + +.. toctree:: + :maxdepth: 4 + + gino.aiocontextvars + gino.api + gino.bakery + gino.crud + gino.declarative + gino.engine + gino.exceptions + gino.json_support + gino.loader + gino.schema + gino.strategies + gino.transaction + +Module contents +--------------- + +.. automodule:: gino + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/en/1.1b2/_sources/reference/api/gino.schema.rst.txt b/docs/en/1.1b2/_sources/reference/api/gino.schema.rst.txt new file mode 100644 index 0000000..36fbb62 --- /dev/null +++ b/docs/en/1.1b2/_sources/reference/api/gino.schema.rst.txt @@ -0,0 +1,7 @@ +gino.schema module +================== + +.. automodule:: gino.schema + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/en/1.1b2/_sources/reference/api/gino.strategies.rst.txt b/docs/en/1.1b2/_sources/reference/api/gino.strategies.rst.txt new file mode 100644 index 0000000..01de55b --- /dev/null +++ b/docs/en/1.1b2/_sources/reference/api/gino.strategies.rst.txt @@ -0,0 +1,7 @@ +gino.strategies module +====================== + +.. automodule:: gino.strategies + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/en/1.1b2/_sources/reference/api/gino.transaction.rst.txt b/docs/en/1.1b2/_sources/reference/api/gino.transaction.rst.txt new file mode 100644 index 0000000..2a28e55 --- /dev/null +++ b/docs/en/1.1b2/_sources/reference/api/gino.transaction.rst.txt @@ -0,0 +1,7 @@ +gino.transaction module +======================= + +.. automodule:: gino.transaction + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/en/1.1b2/_sources/reference/extensions.rst.txt b/docs/en/1.1b2/_sources/reference/extensions.rst.txt new file mode 100644 index 0000000..660c240 --- /dev/null +++ b/docs/en/1.1b2/_sources/reference/extensions.rst.txt @@ -0,0 +1,7 @@ +Extensions +========== + +.. toctree:: + :glob: + + extensions/* diff --git a/docs/en/1.1b2/_sources/reference/extensions/sanic.rst.txt b/docs/en/1.1b2/_sources/reference/extensions/sanic.rst.txt new file mode 100644 index 0000000..1de33f0 --- /dev/null +++ b/docs/en/1.1b2/_sources/reference/extensions/sanic.rst.txt @@ -0,0 +1,141 @@ +============= +Sanic Support +============= + +**THIS IS A WIP** + + +Work with Sanic +--------------- + +Using the Sanic extension, the request handler acquires a lazy connection on each request, +and return the connection when the response finishes by default. + +The lazy connection is actually established if necessary, i.e. just before first access to db. + +This behavior is controlled by app.config.DB_USE_CONNECTION_FOR_REQUEST, which is True by default. + +Supported configurations: + +- DB_HOST +- DB_PORT +- DB_USER +- DB_PASSWORD +- DB_DATABASE +- DB_ECHO +- DB_POOL_MIN_SIZE +- DB_POOL_MAX_SIZE +- DB_USE_CONNECTION_FOR_REQUEST +- DB_KWARGS + +An example server: + +:: + + from sanic import Sanic + from sanic.exceptions import abort + from sanic.response import json + from gino.ext.sanic import Gino + + app = Sanic() + app.config.DB_HOST = 'localhost' + app.config.DB_DATABASE = 'gino' + db = Gino() + db.init_app(app) + + + class User(db.Model): + __tablename__ = 'users' + + id = db.Column(db.BigInteger(), primary_key=True) + nickname = db.Column(db.Unicode()) + + def __repr__(self): + return '{}<{}>'.format(self.nickname, self.id) + + + @app.route("/users/") + async def get_user(request, user_id): + if not user_id.isdigit(): + abort(400, 'invalid user id') + user = await User.get_or_404(int(user_id)) + return json({'name': user.nickname}) + + + if __name__ == '__main__': + app.run(debug=True) + + +Sanic Support +------------- + +To integrate with Sanic, a few configurations needs to be set in +``app.config`` (with default value though): + +- DB_HOST: if not set, ``localhost`` +- DB_PORT: if not set, ``5432`` +- DB_USER: if not set, ``postgres`` +- DB_PASSWORD: if not set, empty string +- DB_DATABASE: if not set, ``postgres`` +- DB_ECHO: if not set, ``False`` +- DB_POOL_MIN_SIZE: if not set, 5 +- DB_POOL_MAX_SIZE: if not set, 10 +- DB_KWARGS; if not set, empty dictionary + +An example: + +.. code-block:: python + + from sanic import Sanic + from gino.ext.sanic import Gino + + app = Sanic() + app.config.DB_HOST = 'localhost' + app.config.DB_USER = 'postgres' + + db = Gino() + db.init_app(app) + + +After ``db.init_app``, a connection pool with configured settings shall be +created and bound to ``db`` when Sanic server is started, and closed on stop. +Furthermore, a lazy connection context is created on each request, and released +on response. That is to say, within Sanic request handlers, you can directly +access db by e.g. ``User.get(1)``, everything else is settled: database pool is +created on server start, connection is lazily borrowed from pool on the first +database access and shared within the rest of the same request handler, and +automatically returned to the pool on response. + +Please be noted that, in the async world, ``await`` may block unpredictably for +a long time. When this world is crossing RDBMS pools and transactions, it is +a very dangerous bite for performance, even causing disasters sometimes. +Therefore we recommend, during the time enjoying fast development, do pay +special attention to the scope of transactions and borrowed connections, make +sure that transactions are closed as soon as possible, and connections are not +taken for unnecessarily long time. As for the Sanic support, if you want to +release the concrete connection in the request context before response is +reached, just do it like this: + +.. code-block:: python + + await request['connection'].release() + + +Or if you prefer not to use the contextual lazy connection in certain handlers, +prefer explicitly manage the connection lifetime, you can always borrow a new +connection by setting ``reuse=False``: + +.. code-block:: python + + async with db.acquire(reuse=False): + # new connection context is created + + +Or if you prefer not to use the builtin request-scoped lazy connection at all, +you can simply turn it off: + +.. code-block:: python + + app.config.DB_USE_CONNECTION_FOR_REQUEST = False + + diff --git a/docs/en/1.1b2/_sources/reference/extensions/starlette.rst.txt b/docs/en/1.1b2/_sources/reference/extensions/starlette.rst.txt new file mode 100644 index 0000000..a7b76d7 --- /dev/null +++ b/docs/en/1.1b2/_sources/reference/extensions/starlette.rst.txt @@ -0,0 +1,86 @@ +================= +Starlette Support +================= + +Work with Starlette +------------------- + +To use GINO with Starlette, the `gino-starlette +`_ package should +be installed first: + +.. code-block:: console + + pip install gino-starlette + +.. note:: + The gino-starlette package supports only GINO 1.0 or later. + Earlier versions of GINO like 0.8.x have built-in Starlette support. + +This extension provides a Starlette middleware to setup and cleanup +database according to the configurations that passed in the ``kwargs`` +parameter. + +The common usage looks like this: + +.. code-block:: python + + from starlette.applications import Starlette + from gino.ext.starlette import Gino + + app = Starlette() + db = Gino(app, **kwargs) + + # Or with application factory + app = Starlette() + db = Gino(**kwargs) + db.init_app(app) + +Configuration +------------- + +The config includes: + ++----------------------------------+-----------------------------------------------------------------------------------------------------------------------+-----------------+ +| Name | Description | Default | ++==================================+=======================================================================================================================+=================+ +| ``driver`` | the database driver | ``asyncpg`` | ++----------------------------------+-----------------------------------------------------------------------------------------------------------------------+-----------------+ +| ``host`` | database server host | ``localhost`` | ++----------------------------------+-----------------------------------------------------------------------------------------------------------------------+-----------------+ +| ``port`` | database server port | ``5432`` | ++----------------------------------+-----------------------------------------------------------------------------------------------------------------------+-----------------+ +| ``user`` | database server user | ``postgres`` | ++----------------------------------+-----------------------------------------------------------------------------------------------------------------------+-----------------+ +| ``password`` | database server password | empty | ++----------------------------------+-----------------------------------------------------------------------------------------------------------------------+-----------------+ +| ``database`` | database name | ``postgres`` | ++----------------------------------+-----------------------------------------------------------------------------------------------------------------------+-----------------+ +| ``dsn`` | a SQLAlchemy database URL to create the engine, its existence will replace all previous connect arguments. | N/A | ++----------------------------------+-----------------------------------------------------------------------------------------------------------------------+-----------------+ +| ``pool_min_size`` | the initial number of connections of the db pool. | N/A | ++----------------------------------+-----------------------------------------------------------------------------------------------------------------------+-----------------+ +| ``pool_max_size`` | the maximum number of connections in the db pool. | N/A | ++----------------------------------+-----------------------------------------------------------------------------------------------------------------------+-----------------+ +| ``echo`` | enable SQLAlchemy echo mode. | N/A | ++----------------------------------+-----------------------------------------------------------------------------------------------------------------------+-----------------+ +| ``ssl`` | SSL context passed to ``asyncpg.connect`` | ``None`` | ++----------------------------------+-----------------------------------------------------------------------------------------------------------------------+-----------------+ +| ``use_connection_for_request`` | flag to set up lazy connection for requests. | N/A | ++----------------------------------+-----------------------------------------------------------------------------------------------------------------------+-----------------+ +| ``kwargs`` | other parameters passed to the specified dialects, like ``asyncpg``. Unrecognized parameters will cause exceptions. | N/A | ++----------------------------------+-----------------------------------------------------------------------------------------------------------------------+-----------------+ + +Lazy Connection +--------------- + +If ``use_connection_for_request`` is set to be True, then a lazy +connection is available at ``request['connection']``. By default, a +database connection is borrowed on the first query, shared in the same +execution context, and returned to the pool on response. If you need to +release the connection early in the middle to do some long-running +tasks, you can simply do this: + +.. code:: python + + await request['connection'].release(permanent=False) diff --git a/docs/en/1.1b2/_sources/reference/extensions/tornado.rst.txt b/docs/en/1.1b2/_sources/reference/extensions/tornado.rst.txt new file mode 100644 index 0000000..c69ef5b --- /dev/null +++ b/docs/en/1.1b2/_sources/reference/extensions/tornado.rst.txt @@ -0,0 +1,5 @@ +=============== +Tornado Support +=============== + +**THIS IS A WIP** diff --git a/docs/en/1.1b2/_sources/reference/history.rst.txt b/docs/en/1.1b2/_sources/reference/history.rst.txt new file mode 100644 index 0000000..65889ae --- /dev/null +++ b/docs/en/1.1b2/_sources/reference/history.rst.txt @@ -0,0 +1,620 @@ +======= +History +======= + +GINO 1.1 +-------- + +1.1.0 (pending) +^^^^^^^^^^^^^^^ + +* Added baked query feature (#478 #659 #667) +* Added ``Query.gino.execution_options`` shortcut (#659) +* Added ``@db.declared_attr(with_table=True)`` (#659) + + +GINO 1.0 +-------- + +Migrating to GINO 1.0 +^^^^^^^^^^^^^^^^^^^^^ + +GINO 1.0 moved the built-in Web framework extensions into separate PyPI +packages. If you're using one of them, you should install GINO 1.0 with extras: + ++------------------------+---------------------------------+ +| Extension Module | Installation in GINO 1.0 | ++========================+=================================+ +| ``gino.ext.starlette`` | ``pip install gino[starlette]`` | ++------------------------+---------------------------------+ +| ``gino.ext.aiohttp`` | ``pip install gino[aiohttp]`` | ++------------------------+---------------------------------+ +| ``gino.ext.sanic`` | ``pip install gino[sanic]`` | ++------------------------+---------------------------------+ +| ``gino.ext.tornado`` | ``pip install gino[tornado]`` | ++------------------------+---------------------------------+ +| ``gino.ext.quart`` | ``pip install gino[quart]`` | ++------------------------+---------------------------------+ + +The new extension packages are backward-compatible, so there's no need to +update the import statements. For example, this will still work in GINO 1.0 if +you installed ``gino[starlette]``:: + + from gino.ext.starlette import Gino + +GINO 1.0 switched to `Poetry `__ for package and +dependency management and started to use the +`src layout `__. This shouldn't +cause any problem using GINO as a dependency, but it does introduce some +changes to the GINO development process: + +* Source files are now located under ``src`` directory. +* The src dist on PyPI does not include tests, docs and some other files due to + a limitation of Poetry. + +1.0.1 (2020-06-08) +^^^^^^^^^^^^^^^^^^ + +* Fixed dependency version range (SQLAlchemy >=1.2.16, <1.4) +* Updated docs (Including contribution by Galden in #660, and Iuliia Volkova in #672) +* Multiple JSON property fixes (#661 #662 #695) +* Fixed extension typing issue (#673 #674) +* Fixed model override behavior (#694) +* Fixed multiple JSON profiles issue (Contributed by Roman Averchenkov in #693 #696) + +1.0.0 (2020-04-26) +^^^^^^^^^^^^^^^^^^ + +* Switched to Poetry for package and dependency management. +* [Breaking] Moved built-in extension modules to separate PyPI packages. +* Switched to src layout. +* Switched to black code style. +* Better documentation. +* [Breaking] ``none_as_none()`` is now always enabled. +* Added representation method for engine. +* Protected the URL instance fed to ``set_bind()`` from manipulation. +* Replaced some ``assert`` with ``AssertionError`` (#258 #655) + + +GINO 0.8 +-------- + +This is also version 1.0 release candidate. + +Migrating to GINO 0.8 +^^^^^^^^^^^^^^^^^^^^^ + +1. contextvars +"""""""""""""" + +We introduced aiocontextvars_ 0.2.0 which is revamped to be compatible with +PEP-567 without manual interference by a few simple implicit patches. To +upgrade to GINO 0.8, please remove the ``enable_inherit()`` or +``disable_inherit()`` calls, because they are the default behavior now thus +no longer exist. However, you'll need to confirm that the event loop in use is +always created **after** importing ``gino`` or ``aiocontextvars``, or the patch +won't work correctly. + +There is nothing to worry about in Python 3.7. + +2. none_as_none +""""""""""""""" + +When GINO tries to load a row with all ``NULL`` values into an instance, it +will now by default return ``None`` instead of an instance with all ``None`` +attributes. To recover the default behavior of 0.7, please specify +``none_as_none(False)`` in affected model loader. + +This is especially applicable to relationship sub-loaders - if the sub-loader +found it all ``NULL``, no instance will be set to parent instance. For +example:: + + child = await Child.load(parent=Parent).query.gino.first() + +If ``child.parent_id`` is ``NULL`` in database, then the ``child`` instance +won't be called with any ``setattr(child, 'parent', ...)`` at all. (If you need +``child.parent == None`` in this case, consider setting default value +``parent = None`` in child model.) + +Please note, it is deprecated to disable ``none_as_none``, and disabling will +be removed in GINO 1.0. + +0.8.7 (2020-04-19) +^^^^^^^^^^^^^^^^^^ + +* Improved error handling when attribute names collide (Contributed by Reskov in #637 #638) +* Fixed ``with_bind`` usability in aiohttp extension (#518) + +0.8.6 (2020-02-10) +^^^^^^^^^^^^^^^^^^ + +* Fixed ``JSONPathType`` bind processor for asyncpg (#609) +* Allowed for primary keys with different names from the database columns (Contributed by Tiago Requeijo in #599 #600) +* Allowed to use simple callable instead of property for one-2-many loading (Contributed by Olexiy in #629) +* Added ``distinct()`` to ``Alias`` (#628) + +0.8.5 (2019-11-19) +^^^^^^^^^^^^^^^^^^ + +* Improved support for ``__tablename__`` in ``declared_attr`` (Contributed by Roald Storm in #592) + +0.8.4 (2019-11-09) +^^^^^^^^^^^^^^^^^^ + +* Better loader support for models in subqueries (#573 #585) +* Allowed ``__tablename__`` to be a ``declared_attr`` (#579 #582) +* Fixed Sanic 19.9.0 compatibility (#569) +* Added one() and one_or_none() (Contributed by Ilaï Deutel in #577) +* Improved Starleet extension compatibility (Contributed by Jim O'Brien in #538) +* Fixed Starlette connection release during exceptions issue (Contributed by qulaz in #533) +* Fixed server event compatibility with Sanic 19.6.2 (Contributed by Julio Lacerda in #520) +* Fixed Grammar (Contributed by Simeon J Morgan in #504) + +0.8.3 (2019-06-06) +^^^^^^^^^^^^^^^^^^ + +* Fixed deprecated warnings in asyncpg dialect and aiohttp (#425) +* Customizable db attribute name in aiohttp app instance (#457) +* Added Starlette support (#486) + +0.8.2 (2019-03-07) +^^^^^^^^^^^^^^^^^^ + +* Added exception for unknown JSON properties (#406 #408) +* Supported Quart 0.7 (#411) +* Accepted kwargs for db init in extensions (#407 #427) +* Added custom config parameter to aiohttp middleware (Contributed by Michał Dziewulski in #440) +* Added NullPool (#437 #441) +* Unpinned dependency versions (#447) +* Added support for SQLAlchemy 1.3 (#433 #451) + +0.8.1 (2018-12-08) +^^^^^^^^^^^^^^^^^^ + +* Alias supported ``Label`` (#365) +* Docs update (#308, 4c59ad, #401 by Pascal van Kooten) +* Version requirement for SQLAlchemy is updated to ``>=1.2`` (#378 #382) +* Added option for SSL in aiohttp extension (Contributed by Martin Zaťko in #387 #393) + * And all other extensions (#395) +* Supported Tornado 5 (#396, also thanks to Vladimir Goncharov) +* Fixed custom JSON/JSONB type support (#402 #403) + +(Most fixes done by Tony Wang) + +0.8.0 (2018-10-16) +^^^^^^^^^^^^^^^^^^ + +* Welcome Tony Wang to the maintenance team (#335) +* Allowed custom column names (#261 #297) +* Allowed column instance in ``model.load()`` (Contributed by Jekel in #323) +* [Breaking] Upgraded to aiocontextvars 0.2.0 (#333) +* Fixed bug that the same empty stack is shared between sub-tasks (#313 #334) +* [Breaking] Made ``none_as_none()`` the default behavior (#351) +* Bug fixes and docs update + + +GINO 0.7 +-------- + +This is also version 1.0 beta 3. + +0.7.7 (2018-12-08) +^^^^^^^^^^^^^^^^^^ + +* Backported fix for custom JSON/JSONB type support (#402 #403) + +0.7.6 (2018-08-26) +^^^^^^^^^^^^^^^^^^ + +* Updated library support (Contributed by Tony Wang in #275 #309) +* Added ``none_as_none()`` (#281 #282) +* Added ``ARRAY`` alias in asyncpg dialect module (Contributed by Mykyta Holubakha in #289) +* Added ``Model.lookup()`` to prevent updating whole table without primary key (#287 #288) +* Added ``DB_ECHO`` in extension options (Contributed by Mykyta Holubakha in #298) +* Fixed broken JSON/JSONB result processor since 0.5.8 (Contributed by Tony Wang in #291 #305) +* Removed bad rollback after a failing commit (Contributed by Tony Wang in #302 #304) +* Fixed to raise ``UninitializedError`` if bind is ``None`` (Contributed by Tony Wang in #307 #310) + +0.7.5 (2018-07-26) +^^^^^^^^^^^^^^^^^^ + +* Added friendly error message when using abstract models by mistake (#224) +* Supported Python 3.7 (Contributed by Tony Wang in #265) +* Updated documentation +* Fixed a bug in TupleLoader (Contributed by Pavol Vargovcik in #279 #280) + +0.7.4 (2018-06-10) +^^^^^^^^^^^^^^^^^^ + +* Added aiocontextvars as required dependency required for Python 3.5 and 3.6 (#228) +* Added Quart support (#213) +* Fixed Tornado options parsing (#231) +* Improved coding style and test coverage + +0.7.3 (2018-05-19) +^^^^^^^^^^^^^^^^^^ + +* Fix for failing binary type (#225) + +0.7.2 (2018-05-15) +^^^^^^^^^^^^^^^^^^ + +* Added prepared statement support (#14) +* Added dsn in extension config (Contributed by Yurii Shtrikker in #215) + +0.7.1 (2018-05-03) +^^^^^^^^^^^^^^^^^^ + +* Added support for inline model constraints (Contributed by Kinware in #198) +* Added docs and tests for using SSL (#202) +* Added ``declared_attr`` (#204) +* Allowed ``ModelLoader`` passively load partial model (#216) + +0.7.0 (2018-04-18) +^^^^^^^^^^^^^^^^^^ + +* Added Python 3.5 support (#187) +* Added support to use ``dict`` as ident for ``Model.get`` (#192) +* Added result loader (partial relationship support) (#13) +* Added documentation on relationship and transaction (#146) + + +GINO 0.6 +-------- + +This is also version 1.0 beta 2. + +Migrating to GINO 0.6 +^^^^^^^^^^^^^^^^^^^^^ + +1. Task Local +""""""""""""" + +We created a new Python package aiocontextvars_ from previous ``local.py``. If +you made use of the task local features, you should install this package. + +Previous ``gino.enable_task_local()`` and ``gino.disable_task_local()`` are +replaced by ``aiocontextvars.enable_inherit()`` and +``aiocontextvars.disable_inherit()``. However in GINO 0.5 they controls the +whole task local feature switch, while aiocontextvars_ by default offers task +local even without ``enable_inherit()``, which controls whether the local +storage should be passed between chained tasks. When enabled, it behaves the +same as enabled in 0.5, but you cannot completely turn off the task local +feature while aiocontextvars_ is installed. + +There is no ``gino.get_local()`` and ``gino.reset_local()`` relevant in +aiocontextvars_. The similar thing is ``aiocontextvars.ContextVar`` instance +through its ``get()``, ``set()`` and ``delete()`` methods. + +Previous ``gino.is_local_root()`` is now +``not aiocontextvars.Context.current().inherited``. + +2. Engine +""""""""" + +GINO 0.6 hides ``asyncpg.Pool`` behind the new SQLAlchemy-alike +``gino.GinoEngine``. Instead of doing this in 0.5:: + + async with db.create_pool('postgresql://...') as pool: + # your code here + +You should change it to this in 0.6:: + + async with db.with_bind('postgresql://...') as engine: + # your code here + +This equals to:: + + engine = await gino.create_engine('postgresql://...') + db.bind = engine + try: + # your code here + finally: + db.bind = None + await engine.close() + +Or:: + + engine = await db.set_bind('postgresql://...') + try: + # your code here + finally: + await db.pop_bind().close() + +Or even this:: + + db = await gino.Gino('postgresql://...') + try: + # your code here + finally: + await db.pop_bind().close() + +Choose whichever suits you the best. + +Obviously ``GinoEngine`` doesn't provide ``asyncpg.Pool`` methods directly any +longer, but you can get the underlying ``asyncpg.Pool`` object through +``engine.raw_pool`` property. + +``GinoPool.get_current_connection()`` is now changed to ``current_connection`` +property on ``GinoEngine`` instances to support multiple engines. + +``GinoPool.execution_option`` is gone, instead ``update_execution_options()`` +on ``GinoEngine`` instance is available. + +``GinoPool().metadata`` is gone, ``dialect`` is still available. + +``GinoPool.release()`` is removed in ``GinoEngine`` and ``Gino``, the +``release()`` method on ``GinoConnection`` object should be used instead. + +These methods exist both in 0.5 ``GinoPool`` and 0.6 ``GinoEngine``: +``close()``, ``acquire()``, ``all()``, ``first()``, ``scalar()``, ``status()``. + +3. GinoConnection +""""""""""""""""" + +Similarly, ``GinoConnection`` in 0.6 is no longer a subclass of +``asyncpg.Connection``, instead it has a ``asyncpg.Connection`` instance, +accessable through ``GinoConnection.raw_connection`` property. + +``GinoConnection.metadata`` is deleted in 0.6, while ``dialect`` remained. + +``GinoConnection.execution_options()`` is changed from a mutable dict in 0.5 to +a method returning a copy of current connection with the new options, the same +as SQLAlchemy behavior. + +``GinoConnection.release()`` is still present, but its default behavior has +been changed to permanently release this connection. You should add argument +``permanent=False`` to remain its previous behavior. + +And ``all()``, ``first()``, ``scalar()``, ``status()``, ``iterate()``, +``transaction()`` remained in 0.6. + +4. Query API +"""""""""""" + +All five query APIs ``all()``, ``first()``, ``scalar()``, ``status()``, +``iterate()`` now accept the same parameters as SQLAlchemy ``execute()``, +meaning they accept raw SQL text, or multiple sets of parameters for +"executemany". Please note, if the parameters are recognized as "executemany", +none of the methods will return anything. Meanwhile, they no longer accept the +parameter ``bind`` if they did. Just use the API on the ``GinoEngine`` or +``GinoConnection`` object instead. + +5. Transaction +"""""""""""""" + +Transaction interface is rewritten. Now in 0.6, a ``GinoTransaction`` object is +provided consistently from all 3 methods:: + + async with db.transaction() as tx: + # within transaction + + async with engine.transaction() as tx: + # within transaction + + async with engine.acquire() as conn: + async with conn.transaction() as tx: + # within transaction + +And different usage with ``await``:: + + tx = await db.transaction() + try: + # within transaction + await tx.commit() + except: + await tx.rollback() + raise + +The ``GinoConnection`` object is available at ``tx.connection``, while +underlying transaction object from database driver is available at +``tx.transaction`` - for asyncpg it is an ``asyncpg.transaction.Transaction`` +object. + +0.6.6 (2018-05-18) +^^^^^^^^^^^^^^^^^^ + +* Backported a fix for failing binary type (#225) + +0.6.5 (2018-04-18) +^^^^^^^^^^^^^^^^^^ + +* Abandoned 0.6.4 and keep 0.6.x stable +* Backported doc for transaction + +0.6.4 (2018-04-16) +^^^^^^^^^^^^^^^^^^ + +Abandoned version, please use 0.7.0 instead. + +0.6.3 (2018-04-08) +^^^^^^^^^^^^^^^^^^ + +* Added aiohttp support +* Added support for calling ``create()`` on model instances (Contributed by Kinware in #178 #180) +* Fixed ``get()`` by string, and misc environment issues (Contributed by Tony Wang in #191 193 #183 #184) + +0.6.2 (2018-03-24) +^^^^^^^^^^^^^^^^^^ + +* Fixed SQLAlchemy prefetch issue (#141) +* Fixed issue that mixin class on Model not working (#174) +* Added more documentation (Thanks Olaf Conradi for reviewing) + +0.6.1 (2018-03-18) +^^^^^^^^^^^^^^^^^^ + +* Fixed ``create`` and ``drop`` for ``Enum`` type (#160) +* A bit more documentation (#159) + +0.6.0 (2018-03-14) +^^^^^^^^^^^^^^^^^^ + +* [Breaking] API Refactored, ``Pool`` replaced with ``Engine`` + + * New API ``Engine`` replaced asyncpg ``Pool`` (#59) + * Supported different dialects, theoretically + * Used aiocontextvars_ instead of builtin task local (#89) +* [Breaking] Fixed query API with ``multiparams`` (executemany) to return correctly (#20) +* [Breaking] The query methods no longer accept the parameter ``bind`` +* [Breaking] ``Gino`` no longer exposes ``postgresql`` types +* Added ``echo`` on engine (#142) +* Added tests to cover 80% of code +* Added ``gino`` extension on ``SchemaItem`` for ``create_all`` and so on (#76 #106) +* Added ``gino`` extension on model classes for ``create()`` or ``drop()`` +* Added ``_update_request_cls`` on ``CRUDModel`` (#147) +* Rewrote the documentation (#146) + +.. _aiocontextvars: https://github.com/fantix/aiocontextvars + + +GINO 0.5 +-------- + +This is also version 1.0 beta 1. + +0.5.8 (2018-02-14) +^^^^^^^^^^^^^^^^^^ + +* Preparing for 0.6.0 which will be a breaking release +* Fixed wrong value of ``Enum`` in creation (Contributed by Sergey Kovalev in #126) + +0.5.7 (2017-11-24) +^^^^^^^^^^^^^^^^^^ + +This is an emergency fix for 0.5.6. + +* Fixed broken lazy connection (Contributed by Ádám Barancsuk in #114) +* Added ``Model.outerjoin`` + +0.5.6 (2017-11-23) +^^^^^^^^^^^^^^^^^^ + +* Changed to use unnamed statement when possible (#80 #90) +* Added more example (Contributed by Kentoseth in #109) +* Added ``Model.join`` and made ``Model`` selectable (Contributed by Ádám Barancsuk in #112 #113) + +0.5.5 (2017-10-18) +^^^^^^^^^^^^^^^^^^ + +* Ensured clean connection if transaction acquire fails (Contributed by Vladimir Goncharov in #87) +* Added ability to reset local storage (#84) +* Fixed bug in JSON property update +* Added update chaining feature + +0.5.4 (2017-10-04) +^^^^^^^^^^^^^^^^^^ + +* Updated example (Contributed by Kinware in #75) +* Added ``Model.insert`` (Contributed by Neal Wang in #63) +* Fixed issue that non-lazy acquiring fails dirty (#79) + +0.5.3 (2017-09-23) +^^^^^^^^^^^^^^^^^^ + +* Fixed ``no module named cutils`` error (Contributed by Vladimir Goncharov in #73) + +0.5.2 (2017-09-10) +^^^^^^^^^^^^^^^^^^ + +* Added missing driver name on dialect (#67) +* Fixed dialect to support native decimal type (#67) + +0.5.1 (2017-09-09) +^^^^^^^^^^^^^^^^^^ + +This is an emergency fix for 0.5.0. + +* Reverted the extension, back to pure Python (#60) +* Used SQLAlchemy ``RowProxy`` +* Added ``first_or_404`` +* Fixed bug that ``GinoPool`` cannot be inherited + +0.5.0 (2017-09-03) +^^^^^^^^^^^^^^^^^^ + +* [Breaking] Internal refactor: extracted and isolated a few modules, partially rewritten + + * Extracted CRUD operations + * Core operations are moved to ``dialect`` and execution context + * Removed ``guess_model``, switched to explicit execution options + * Turned ``timeout`` parameter to an execution option + * Extracted ``pool``, ``connection`` and ``api`` from ``asyncpg_delegate`` +* Added support for SQLAlchemy execution options, and a few custom options +* [Breaking] Made `Model.select` return rows by default (#39) +* Moved `get_or_404` to extensions (#38) +* Added iterator on model classes (#43) +* Added Tornado extension (Contributed by Vladimir Goncharov) +* Added `Model.to_dict` (#47) +* Added an extension module to update `asyncpg.Record` with processed results + + +Early Development Releases +-------------------------- + +Considered as alpha releases. + + +0.4.1 (2017-08-20) +^^^^^^^^^^^^^^^^^^ + +* Support ``select`` on model instance + +0.4.0 (2017-08-15) +^^^^^^^^^^^^^^^^^^ + +* Made ``get_or_404`` more friendly when Sanic is missing (Contributed by Neal Wang in #23 #31) +* Delegated ``sqlalchemy.__all__`` (Contributed by Neal Wang in #10 #33) +* [Breaking] Rewrote JSON/JSONB support (#29) +* Added ``lazy`` parameter on ``db.acquire`` (Contributed by Binghan Li in #32) +* Added Sanic integration (Contributed by Binghan Li, Tony Wang in #30 #32 #34) +* Fixed ``iterate`` API to be compatible with asyncpg (#32) +* Unified exceptions +* [Breaking] Changed ``update`` API (#29) +* Bug fixes + +0.3.0 (2017-08-07) +^^^^^^^^^^^^^^^^^^ + +* Supported ``__table_args__`` (#12) +* Introduced task local to manage connection in context (#19) +* Added ``query.gino`` extension for in-place execution +* Refreshed README (#3) +* Adopted PEP 487 (Contributed by Tony Wang in #17 #27) +* Used ``weakref`` on ``__model__`` of table and query (Contributed by Tony Wang) +* Delegated asyncpg ``timeout`` parameter (Contributed by Neal Wang in #16 #22) + +0.2.3 (2017-08-04) +^^^^^^^^^^^^^^^^^^ + +* Supported any primary key (Contributed by Tony Wang in #11) + +0.2.2 (2017-08-02) +^^^^^^^^^^^^^^^^^^ + +* Supported SQLAlchemy result processor +* Added rich support on JSON/JSONB +* Bug fixes + +0.2.1 (2017-07-28) +^^^^^^^^^^^^^^^^^^ + +* Added ``update`` and ``delete`` API + +0.2.0 (2017-07-28) +^^^^^^^^^^^^^^^^^^ + +* Changed API, no longer reuses asyncpg API + +0.1.1 (2017-07-25) +^^^^^^^^^^^^^^^^^^ + +* Added ``db.bind`` +* API changed: parameter ``conn`` renamed to optional ``bind`` +* Delegated asyncpg Pool with ``db.create_pool`` +* Internal enhancement and bug fixes + +0.1.0 (2017-07-21) +^^^^^^^^^^^^^^^^^^ + +* First release on PyPI. diff --git a/docs/en/1.1b2/_sources/tutorials.rst.txt b/docs/en/1.1b2/_sources/tutorials.rst.txt new file mode 100644 index 0000000..6b3bb98 --- /dev/null +++ b/docs/en/1.1b2/_sources/tutorials.rst.txt @@ -0,0 +1,9 @@ +Tutorials +========= + +.. toctree:: + :glob: + + tutorials/announcement.rst + tutorials/tutorial.rst + tutorials/* diff --git a/docs/en/1.1b2/_sources/tutorials/announcement.rst.txt b/docs/en/1.1b2/_sources/tutorials/announcement.rst.txt new file mode 100644 index 0000000..f159e02 --- /dev/null +++ b/docs/en/1.1b2/_sources/tutorials/announcement.rst.txt @@ -0,0 +1,297 @@ +官宣：Python 异步编程再添一利器 +=============================== + + GINO 填补了国内外 asyncio ORM 领域的空白 + +随着 Tornado\ [1]_ 和 asyncio\ [2]_ 等框架的陆续涌现，Python 异步编程这个话题也在逐渐升温。\ +在这个烧脑的异步世界里，有没有办法可以既方便快捷、又简单明了地访问数据库呢？GitHub 千星项目 +`GINO `__ 了解一下！ + +.. image:: ../images/python-gino.webp + :align: center + + +GINO 是谁 +--------- + +GINO 是一个“轻量级”异步 ORM 框架，它的全称是 GINO Is Not ORM，借鉴了 GNU is Not Unix +的递归定义\ [3]_\ 手法。所以，GINO 一定要全！部！大！写！如果像这样“Gino”就变成了人名，\ +你肯定要问一句“这是谁”。 + +ORM，即关系对象映射（Object-Relational Mapping\ [4]_\ ），是一类开发人员喜闻乐见的效率工具，\ +它们“极大地”提升了写代码的幸福指数。GINO 是用来访问数据库的，也提供了对象映射的工具，那为什么非说 +GINO 不是 ORM 呢？ + +因为物极必反，ORM 在带来生活便利的同时，也是 bug 生长的温床——传统 ORM 往往会选择牺牲明确性\ +（explicitness）来换取便捷性（convenience），再加上 Python 得天独厚的灵活性（flexibility），\ +创造出了一种爆炸式的化学反应。一旦代码初具规模，项目或多或少都会遇到 ORM 反噬的情景：\ +性能莫名其妙的差、出问题找不到原因、为了鸡毛蒜皮的小事大动干戈。随便一句 ``current_user.name`` +都有可能触发一大堆意想不到的数据库调用，这代码你让我怎么调试？ + +传统 ORM 的学习曲线前平后陡，能在快速原型开发中大展身手，\ +但应用到大型项目中却十分考验开发人员的平均水平。 + +所有这些问题如果再放进异步编程的环境里，那就是 O(n\ :sup:`2`) 的复杂度了——哦不，是 +O(2\ :sup:`n`)。这对于一款优秀的异步 ORM 框架来说是不可接受的，所以 GINO 是 ORM 但不是一个传统的 +ORM，正犹如 GNU 不是一个传统的 Unix 一样，形似而神不似。 + +所以在 2017 年创作之初，我就给 GINO 定下了两个业绩目标：1) 方便快捷，2) 简单明了。三年后的今天，\ +我索性在 1.0 稳定版发布的前夕做个年终总结。 + + +先说“方便快捷” +-------------- + + “方便快捷”主要说的是开发效率。 + +重视开发效率的概念对于写 Python 的同学来说可能并不陌生，某些场景下，\ +开发人员的时间确实比机器的时间值钱。所以，传统 ORM 里的对象映射不能丢。 + +:: + + from gino import Gino + db = Gino() + class User(db.Model): + __tablename__ = "users" + id = db.Column(db.Integer, primary_key=True) + name = db.Column(db.String) + +这么定义表结构甚至让人有点小兴奋。咦，为什么这么眼熟？ + +没有错，这就是 SQLAlchemy ORM\ [5]_ 的定义风格。GINO 并不是从头造轮子，而是在 SQLAlchemy +core\ [6]_\ （SQLAlchemy 中负责构建 SQL 的底层核心）的基础上开发的。这么做除了能保持熟悉的味道\ +（以节省学习和迁移成本），更重要的是带来了整个 SQLAlchemy 的生态环境：开箱即用的数据库变更管理工具 +Alembic\ [7]_\ 、各种 SQLAlchemy 的增强插件\ [8]_\ 、专业领域的 PostGIS/geoalchemy\ [9]_\ +等，GINO 全都兼容。 + +是不是十分方便、十分快捷？不止这样。 + +GINO 一站式地解决了常用 CRUD 快捷方式\ [10]_\ 、上下文管理（aiocontextvars\ [11]_\ [12]_\ ）、 +数据库事务封装和嵌套\ [13]_\ 、连接池管理和懒加载\ [14]_\ 等多项便捷功能，无额外依赖关系，即装即用。 + +:: + + daisy = await User.create(name="daisy") + await daisy.update(name="Daisy").apply() + +GINO 还提供了\ [15]_\ 各大流行异步 Web 框架的定制版插件，能叫上名字的像 Tornado\ [1]_\ 、\ +aiohttp\ [16]_\ 、Sanic\ [17]_\ 、FastAPI\ [18]_\ /Starlette\ [19]_\ 、Quart\ [20]_\ +什么的都有，从简单示范到生产环境的各种例子品种齐全，妈妈再也不用担心我不会集成 Web 框架了。 + +为了让不同应用场景下的用户体验到最大的善意，GINO 目前支持三种不同程度的用法，成功实现了对同期竞品 +asyncpgsa\ [21]_ 的降维打击： + +1. 最少侵入型\ [22]_\ ：SQLAlchemy core 原教旨主义者，只有异步执行时才用到 GINO。 +2. 终身不婚型\ [23]_\ ：天生厌恶“对象”，只愿定义“表”，空手接 SQL。 +3. 火力全开型\ [24]_\ ：最大程度的便利，非典型异步 ORM。 + +最后，虽然是 Python（绝不是黑哈），但 GINO 在执行效率上也没落下。基于 MagicStack 出品必属精品的、\ +一秒可读百万行的 asyncpg\ [25]_\ ，以及 uvloop\ [26]_\ （可选）的强力加持，GINO +跑起来也是可以飞快的，被广泛应用于诸如实时汇率、聊天机器人、在线游戏等高并发领域，\ +深受俄罗斯和乌克兰人民的爱戴。 + + +再说“简单明了” +-------------- + + Explicit is better than implicit. + + Simple is better than complex. + + –The Zen of Python, PEP 20\ [27]_ + +Python 之禅完美表达了 GINO 的立场——明确性（explicitness）对于上了规模的异步工程项目来说尤为重要，\ +因此 GINO 的很多设计都受到了明确性的影响。 + +比如说，GINO 的 ``Model`` 是完全无状态的普通 Python 对象（POPO\ [28]_\ —— 例如前面的 ``User`` +类，它的实例 ``daisy`` 就是内存里面的常规对象，你可以用 ``daisy.name`` 访问属性，也可以用 +``daisy.name = "DAISY"`` 来修改属性，或者用 ``u = User()`` 来创建新的实例，\ +这些操作都不会访问数据库，绝对绿色环保无毒副作用。 + +等到需要操作数据库的时候，你一定会有感知的。比如执行 ``INSERT`` 要用 +``u = await User.create()``\ ，而 ``UPDATE`` 则是 +``await u.update(name="Daisy").apply()``\ 。 + +.. hint:: + + 其中，``u.update(name="Daisy")`` 与 ``u.name = "Daisy"`` 类似，\ + 都是只在内存里修改对象的属性，不同的是 ``u.update()`` 还会返回一个包含本次变更的中间结果，\ + 对其执行 ``await xxx.apply()`` 则会将这些变更应用到数据库里。 + +这里的 ``await`` 就是明确性的关键，意味着我们要跳出去执行数据库操作了。换句话说，没有 ``await`` +就没有数据库操作。 + +另一方面，对于如何将数据库查询结果组装成内存对象及其属性，GINO +也有一套精妙的显式机制——可定制化的加载器 loaders\ [29]_\ 。对于简单直观的一对一加载，GINO +自然是伺候到家的，比如用 ``u = await User.get(1)`` 可以直接获取到 ID 为 ``1`` 的用户对象。\ +但是对于更复杂的查询，GINO 不会去无端猜测主人的意图，而全权交给用户来明确地定义。\ +加载器的用法也是很简单的，比如一个用户可能写了很多本书： + +:: + + class Book(db.Model): + __tablename__ = "books" + id = db.Column(db.Integer, primary_key=True) + title = db.Column(db.String) + author_id = db.ForeignKey("users.id") + +然后这样来加载这种多对一关系，以同时获取所有的书和他们的作者： + +:: + + query = Book.outerjoin(User).select() + loader = Book.load(author=User) + async for book in query.gino.load(loader).iterate(): + print(book.title, "written by", book.author.name) + +很简单的一个外连接查询 ``Book.outerjoin(User)``\ ，配合一个直观的加载器 +``Book.load(author=User)``\ ，就实现了： + +1. 执行 ``SELECT * FROM books LEFT JOIN users ON ...``\ ； +2. 将数据库返回结果的每一行中，属于 ``books`` 的字段加载成一个 ``Book`` 实例； +3. 然后将该行中剩下的属于 ``users`` 的字段加载成一个 ``User`` 实例； +4. 最后将 ``User`` 实例设置到 ``Book`` 实例的 ``author`` 属性上。 + +既简单又明了有没有！你甚至可以手写任何 SQL，然后定制加载器自动加载成期望的对象关系，\ +精准控制加载行为，指哪儿打哪儿。GINO 还有很多类似的特性，在这里就不一一列举了。 + + +优势与不足 +---------- + +随着这几年 GINO 不断演进成熟，Python 开源社区里也相继出现了像 Tortoise +ORM\ [30]_\ 、ORM\ [31]_\ （是的，这个项目就叫 ORM……我真 ORZ。出品方是 Encode，Starlette +就是他们的作品）等优秀的异步 ORM 框架。它们关注的重点与 GINO 稍有不同，但都是同行就不多评价了。 + +GINO 的最大优势还是在于充分平衡了开发效率和明确性之间的辩证矛盾关系，用 GINO 开发应用程序的时候\ +不用担心会被意料之外的行为所惊吓到，同时也不需要为这种明确性付出过大的工程代价，上手后依然可以快速、\ +快乐地编程。同时，大量的成功案例也证明了 GINO 已经初步具备发布 1.0 稳定版的各种条件，\ +可以谨慎地用于生产环境了。 + +以下是近来统计到的关于 GINO 的应用案例： + +- 笔者工作上开发的一个服务：\ https://github.com/uc-cdis/metadata-service +- 还是笔者自己写的一个工具：\ https://github.com/fantix/aintq +- 一个汇率 API 服务：\ https://exchangeratesapi.io/ + + .. image:: ../images/exchangeratesapi.webp + :align: center + +- 各种 Telegram、Discord 的 Bot。 +- ArchLinux 用户包：\ https://aur.archlinux.org/packages/python-gino/ + + .. image:: ../images/archlinux.webp + :align: center + +- https://github.com/bryanforbes/gino-stubs/ +- 俄语教程：\ https://www.youtube.com/watch?v=WW4rOnfhiQY +- 高性能模板项目：\ https://github.com/leosussan/fastapi-gino-arq-uvicorn +- 还有几个商用的，但没征得同意就不贴出来了。 + +另外，GINO 还贴心地提供了中文文档\ [32]_\ ，从上手教程到原理说明应有尽有（虽然文档还在努力编写中！）： + +.. image:: ../images/docs.webp + :align: center + +GINO 目前的不足之处还有一些，比如没有照顾到 Python 3 的类型提示，因此还不能完全发挥 IDE 的潜能\ +（上面那个 gino-stubs 就是有人受不了了自己写了一个类型注解）。MySQL 目前也是不支持的，但 GINO +从比较早就解耦了不同 SQL 方言和驱动的集成，所以这些功能会陆续在 1.1 和 1.2 版本中跟上。 + + +建设社会主义 +------------ + +GINO 是一个开源项目，所以欢迎大家一起来建设！长期活跃的贡献者还能获赠价值 **4888 元**\ 的 PyCharm +专业版全家桶 License 一枚\ [33]_\ （没有发票）。 + +目前急需帮助的有： + +1. 各个 Web 框架插件的维护工作需要多人认领； +2. 更多的例子和文档，以及中文、俄文的翻译； +3. MySQL 的支持。 + +以及下面这些一直需要的帮助： + +1. 用 GINO，找 bug，提建议； +2. 修 bug，做功能，提 PR； +3. 维护社区，回答问题，参与讨论； +4. 最后也是最重要的：\ `去 GitHub 上给 GINO 加一颗星星！ + `__ + +.. image:: ../images/happy-hacking.png + :align: center + + +关于作者 +-------- + +87 年生人，6 岁开始接触编程，二十五六年的编程史和十三四年的工作经验教会了我许多软件开发的奥义。\ +小时候写 GBasic、QBasic 和 Visual Basic；大学里开始写 Java 并接触到了 FreeBSD 和 Ubuntu +等开源项目且一发不可收拾；工作头五年转向了 Python，通过 Twisted 和 Eventlet 等项目了解了异步编程，\ +期间贡献了 Gevent 的 Python 3 迁移；也曾在创业的潮流中留下身影，亲身经历并见证了软件技术随着手游、\ +新媒体、矿圈、互金、电商、社交、文娱、汽车等行业的起起伏伏；目前在芝大继续做生物大数据相关的开源项目。\ +业余时间除了开发维护 GINO 项目外，还会偶尔修一修 uvloop、asyncpg 和 CPython 的 bug :P + +特别感谢 `Tony Wang `__ 对 GINO 项目的贡献，以及\ `所有人 +`__\ 的贡献。 + + +参考文献 +-------- + +.. [1] Facebook. Tornado. https://zh.wikipedia.org/wiki/Tornado. +.. [2] Python Software Foundation. asyncio — 异步 I/O. + https://docs.python.org/zh-cn/3/library/asyncio.html. +.. [3] 维基百科. GNU. https://zh.wikipedia.org/wiki/GNU. +.. [4] 维基百科. 对象关系映射. + `https://zh.wikipedia.org/wiki/对象关系映射 + `__. +.. [5] 维基百科. SQLAlchemy. https://zh.wikipedia.org/wiki/SQLAlchemy. +.. [6] Michael Bayer. SQLAlchemy Core - SQLAlchemy. Documentation. + https://docs.sqlalchemy.org/en/13/core/index.html. +.. [7] Michael Bayer. Welcome to Alembic’s documentation!. + https://alembic.sqlalchemy.org/en/latest/. +.. [8] Hong Minhee. A curatedlist of awesome tools for SQLAlchemy. + https://github.com/dahlia/awesome-sqlalchemy. +.. [9] Ricardo GarciaSilva. Does it have postgis support?. + https://github.com/python-gino/gino/issues/627. +.. [10] Fantix King. GINO 基础教程 - 增删改查. + https://python-gino.org/docs/zh/master/tutorials/tutorial.html#crud-operations. +.. [11] Python Software Foundation. contextvars —Context Variables. + https://docs.python.org/3/library/contextvars.html. +.. [12] Fantix King. gino/aiocontextvars.py. + https://github.com/python-gino/gino/blob/f2c273a43a3ed893a767d4239046f2befabf510d/src/gino/aiocontextvars.py. +.. [13] Fantix King. 数据库事务. + https://python-gino.org/docs/zh/master/how-to/transaction.html. +.. [14] Fantix King. 引擎与连接. + https://python-gino.org/docs/zh/master/explanation/engine.html. +.. [15] GINO Community. GINO Community. https://github.com/python-gino/. +.. [16] aiohttp maintainers. Welcome to AIOHTTP. https://docs.aiohttp.org/en/stable/. +.. [17] Sanic Community. SanicFramework. https://sanicframework.org/. +.. [18] Sebastián Ramírez. FastAPI. https://fastapi.tiangolo.com/. +.. [19] Encode OSS. Starlette. https://www.starlette.io/. +.. [20] Philip Jones. Quart Documentation. https://pgjones.gitlab.io/quart/. +.. [21] Canopy. asyncpgsa - A wrapper around asyncpg for use with sqlalchemy. + https://github.com/CanopyTax/asyncpgsa. +.. [22] Fantix King. 表结构定义 -GINO 引擎. + https://pythongino.org/docs/zh/master/how-to/schema.html#gino-engine. +.. [23] Fantix King. 表结构定义 - GINO core. + https://python-gino.org/docs/zh/master/how-to/schema.html#gino-core. +.. [24] Fantix King. 表结构定义 - GINO ORM. + https://python-gino.org/docs/zh/master/how-to/schema.html#gino-orm. +.. [25] MagicStack Inc. + asyncpg - A fast PostgreSQL Database Client Library for Python/asyncio. + https://github.com/MagicStack/asyncpg. +.. [26] MagicStack Inc. uvloop -Ultra fast asyncio event loop. + https://github.com/MagicStack/uvloop. +.. [27] Tim Peters. PEP ‒ The Zenof Python. https://www.python.org/dev/peps/pep-0020/. +.. [28] Wikipedia. Plain old Java object. + https://en.wikipedia.org/wiki/Plain_old_Java_object. +.. [29] Fantix King. 加载器与关系. + https://python-gino.org/docs/zh/master/how-to/loaders.html. +.. [30] Andrey Bondar. Tortoise ORM. https://tortoise.github.io/. +.. [31] Encode OSS. ORM - An async ORM. https://github.com/encode/orm. +.. [32] Fantix King. 欢迎来到 GINO 的文档！. + https://python-gino.org/docs/zh/master/index.html. +.. [33] JetBrains s.r.o. Open Source Licenses. + https://www.jetbrains.com/community/opensource/#support. diff --git a/docs/en/1.1b2/_sources/tutorials/fastapi.rst.txt b/docs/en/1.1b2/_sources/tutorials/fastapi.rst.txt new file mode 100644 index 0000000..f256254 --- /dev/null +++ b/docs/en/1.1b2/_sources/tutorials/fastapi.rst.txt @@ -0,0 +1,669 @@ +Build a FastAPI Server +====================== + +In this tutorial, we'll build a production-ready FastAPI_ server together. +The full functional example is available `here +`__. + +Our application stack will look like this: + +.. image:: ../images/gino-fastapi.svg + :align: center + + +.. _FastAPI: https://fastapi.tiangolo.com/ + + +Start a New Project +------------------- + +Instead of pip, let's use the shiny Poetry_ to manage our project. Follow the link to +`install Poetry `_, and create our new +project in an empty directory: + + +.. code-block:: console + + $ mkdir gino-fastapi-demo + $ cd gino-fastapi-demo + $ git init + $ poetry init + +Then follow the Poetry_ guide to finish the initialization - you may say "no" to the +interactive dependency creation, because we will add them manually. It is okay to use +the default values in the other steps of the guide, and make sure the package name +remains ``gino-fastapi-demo``. + +.. _Poetry: https://python-poetry.org/ + + +Add Dependencies +---------------- + +FastAPI_ is built on top of the Starlette_ framework, so we shall use the `GINO +extension for Starlette `_. Simply run: + +.. code-block:: console + + $ poetry add gino[starlette] + +Then let's add FastAPI_, together with the lightning-fast ASGI_ server Uvicorn_, and +Gunicorn_ as a production application server: + +.. code-block:: console + + $ poetry add fastapi uvicorn gunicorn + +For database migration, we'll use Alembic_. Because it uses normal DB-API_, we need +psycopg_ here too: + +.. code-block:: console + + $ poetry add alembic psycopg2 + +At last, let's add pytest_ in the development environment for testing. We also want to +add the requests_ library to use the Starlette_ |TestClient|_: + +.. code-block:: console + + $ poetry add -D pytest requests + +.. hint:: + + With the steps above, Poetry_ will automatically create a virtualenv_ for you + behind the scene, and all the dependencies are installed there. We will assume + using this for the rest of the tutorial. But you're free to create your own + virtualenv_, and Poetry_ will honor it when it's activated. + +That's all, this is my ``pyproject.toml`` created by Poetry_, yours should look similar: + +.. code-block:: toml + + [tool.poetry] + name = "gino-fastapi-demo" + version = "0.1.0" + description = "" + authors = ["Fantix King "] + + [tool.poetry.dependencies] + python = "^3.8" + gino = {version = "^1.0", extras = ["starlette"]} + fastapi = "^0.54.1" + uvicorn = "^0.11.3" + gunicorn = "^20.0.4" + alembic = "^1.4.2" + psycopg2 = "^2.8.5" + + [tool.poetry.dev-dependencies] + pytest = "^5.4.1" + requests = "^2.23.0" + + [build-system] + requires = ["poetry>=0.12"] + build-backend = "poetry.masonry.api" + +.. image:: ../images/gino-fastapi-poetry.svg + :align: right + +And there's also an auto-generated ``poetry.lock`` file with the frozen versions. The +directory layout should look like the diagram on the right. Now let's add the two files +to the Git repository (we will skip showing these git operations in future steps): + +.. code-block:: console + + $ git add pyproject.toml poetry.lock + $ git commit -m 'add project dependencies' + +.. _Starlette: https://www.starlette.io/ +.. _ASGI: https://asgi.readthedocs.io/ +.. _Uvicorn: https://www.uvicorn.org/ +.. _Gunicorn: https://gunicorn.org/ +.. _Alembic: https://alembic.sqlalchemy.org/ +.. _DB-API: https://www.python.org/dev/peps/pep-0249/ +.. _psycopg: https://www.psycopg.org/ +.. _pytest: https://docs.pytest.org/ +.. _virtualenv: https://virtualenv.pypa.io/ +.. _requests: https://requests.readthedocs.io/ + + +Write a Simple Server +--------------------- + +Now let's write some Python code. + +We'll create an extra ``src`` directory to include all the Python files, as demonstrated +in the diagram below. This is known as the "`src layout +`_" providing a cleaner hierarchy. + +.. image:: ../images/gino-fastapi-src.svg + :align: right + +The root Python package of our project is named as ``gino_fastapi_demo``, under which we +will create two Python modules: + +* ``asgi`` as the ASGI entry point - we'll feed it to the ASGI server +* ``main`` to initialize our server + +Here's ``main.py``:: + + from fastapi import FastAPI + + def get_app(): + app = FastAPI(title="GINO FastAPI Demo") + return app + +And we'll simply instantiate our application in ``asgi.py``:: + + from .main import get_app + + app = get_app() + +Then run ``poetry install`` to link our Python package into the ``PYTHONPATH`` in +development mode. We'll be able to start a Uvicorn development server after that: + +.. code-block:: console + + $ poetry install + Installing dependencies from lock file + + No dependencies to install or update + + - Installing gino-fastapi-demo (0.1.0) + + $ poetry run uvicorn gino_fastapi_demo.asgi:app --reload + INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) + INFO: Started reloader process [53010] + INFO: Started server process [53015] + INFO: Waiting for application startup. + INFO: Application startup complete. + +The ``--reload`` option enables Uvicorn to automatically reload the server for us when +the Python source code is updated. Now access http://127.0.0.1:8000/docs to see the +Swagger UI of our new FastAPI server. + +.. hint:: + + As mentioned previously, if you're in your own virtualenv, the command ``poetry run + uvicorn`` can be simplified as just ``uvicorn``. + + ``poetry run`` is a convenient shortcut to run the following command in the + virtualenv managed by Poetry. + + +Add GINO Extension +------------------ + +.. image:: ../images/gino-fastapi-config.svg + :align: right + +Now let's add GINO to our server. + +First of all, we need a way to configure the database. In this tutorial, we'll use the +`configuration system `_ from Starlette_. +Add ``src/gino_fastapi_demo/config.py`` as follows:: + + from sqlalchemy.engine.url import URL, make_url + from starlette.config import Config + from starlette.datastructures import Secret + + config = Config(".env") + + DB_DRIVER = config("DB_DRIVER", default="postgresql") + DB_HOST = config("DB_HOST", default=None) + DB_PORT = config("DB_PORT", cast=int, default=None) + DB_USER = config("DB_USER", default=None) + DB_PASSWORD = config("DB_PASSWORD", cast=Secret, default=None) + DB_DATABASE = config("DB_DATABASE", default=None) + DB_DSN = config( + "DB_DSN", + cast=make_url, + default=URL( + drivername=DB_DRIVER, + username=DB_USER, + password=DB_PASSWORD, + host=DB_HOST, + port=DB_PORT, + database=DB_DATABASE, + ), + ) + DB_POOL_MIN_SIZE = config("DB_POOL_MIN_SIZE", cast=int, default=1) + DB_POOL_MAX_SIZE = config("DB_POOL_MAX_SIZE", cast=int, default=16) + DB_ECHO = config("DB_ECHO", cast=bool, default=False) + DB_SSL = config("DB_SSL", default=None) + DB_USE_CONNECTION_FOR_REQUEST = config( + "DB_USE_CONNECTION_FOR_REQUEST", cast=bool, default=True + ) + DB_RETRY_LIMIT = config("DB_RETRY_LIMIT", cast=int, default=1) + DB_RETRY_INTERVAL = config("DB_RETRY_INTERVAL", cast=int, default=1) + +This config file will load from environment variable first, if not found then from a +file named ``.env`` from current path (usually the project root directory), and at last +use the default value defined above. For example, you can either overwrite in CLI +directly like this: + +.. code-block:: console + + $ DB_HOST=localhost DB_USER=postgres poetry run uvicorn gino_fastapi_demo.asgi:app --reload + +.. image:: ../images/gino-fastapi-env.svg + :align: right + +Or set them in the file ``.env`` (this file must not be committed into Git, remember to +add it to ``.gitignore``): + +.. code-block:: bash + + DB_HOST=localhost + DB_USER=postgres + +Now it's time to create a PostgreSQL_ database and set the connection variables +correctly here. This is usually something like ``createdb yourdbname``, but it may vary +across different platforms, so we won't cover this part in this tutorial. + +.. tip:: + + Alternatively, you could also set ``DB_DSN`` to for example + ``postgresql://user:password@localhost:5432/dbname`` to override the other individual + config values like ``DB_HOST`` defined before ``DB_DSN``. + + If defined, ``DB_DSN`` always have the higher priority over the individual ones, + regardless of where they are defined - even if ``DB_HOST`` is defined in environment + variable and ``DB_DSN`` is defined in ``.env`` file, ``DB_HOST`` is still ignored. + Default value doesn't count. + +.. image:: ../images/gino-fastapi-models.svg + :align: right + +Then, create a new Python sub-package ``gino_fastapi_demo.models`` to encapsulate +database-related code, and add the code below to +``src/gino_fastapi_demo/models/__init__.py``:: + + from gino.ext.starlette import Gino + + from .. import config + + db = Gino( + dsn=config.DB_DSN, + pool_min_size=config.DB_POOL_MIN_SIZE, + pool_max_size=config.DB_POOL_MAX_SIZE, + echo=config.DB_ECHO, + ssl=config.DB_SSL, + use_connection_for_request=config.DB_USE_CONNECTION_FOR_REQUEST, + retry_limit=config.DB_RETRY_LIMIT, + retry_interval=config.DB_RETRY_INTERVAL, + ) + +At last, modify ``src/gino_fastapi_demo/main.py`` to install the GINO extension: + +.. code-block:: diff + + from fastapi import FastAPI + + + +from .models import db + + def get_app(): + app = FastAPI(title="GINO FastAPI Demo") + + db.init_app(app) + return app + +Saving the file, you should see the Uvicorn server reloads our changes and connects to +the database: + +.. code-block:: console + + WARNING: Detected file change in 'src/gino_fastapi_demo/main.py'. Reloading... + INFO: Shutting down + INFO: Waiting for application shutdown. + INFO: Application shutdown complete. + INFO: Finished server process [63562] + INFO: Started server process [63563] + INFO: Waiting for application startup. + INFO: Connecting to the database: postgresql://fantix:***@localhost + INFO: Database connection pool created: + INFO: Application startup complete. + +.. _PostgreSQL: https://www.postgresql.org/ + + +Create Models and API +--------------------- + +.. image:: ../images/gino-fastapi-models-users.svg + :align: right + +It's time to implement the API now. Let's say we are building a user management service, +through which we could add users, list users and delete users. + +First of all, we need a database table ``users`` to store the data, mapped to a GINO +model named ``User``. We shall add the model in ``gino_fastapi_demo.models.users``:: + + from . import db + + class User(db.Model): + __tablename__ = "users" + + id = db.Column(db.BigInteger(), primary_key=True) + nickname = db.Column(db.Unicode(), default="unnamed") + +.. image:: ../images/gino-fastapi-views.svg + :align: right + +The model definition is simple enough to explain itself. + +Then we only have to use it properly in the API implementation, for which we'll create a +new Python sub-package ``gino_fastapi_demo.views``, and a new module +``gino_fastapi_demo.views.users`` as follows:: + + from fastapi import APIRouter + from pydantic import BaseModel + + from ..models.users import User + + router = APIRouter() + + @router.get("/users/{uid}") + async def get_user(uid: int): + user = await User.get_or_404(uid) + return user.to_dict() + + class UserModel(BaseModel): + name: str + + @router.post("/users") + async def add_user(user: UserModel): + rv = await User.create(nickname=user.name) + return rv.to_dict() + + @router.delete("/users/{uid}") + async def delete_user(uid: int): + user = await User.get_or_404(uid) + await user.delete() + return dict(id=uid) + + def init_app(app): + app.include_router(router) + +The |APIRouter|_ holds our new APIs locally, and ``init_app`` is used to integrate it +into our FastAPI application. Here we want some `inversion of control`_: let's make the +APIs plugable, so that we don't have to import all possible future views manually. We +shall use the `Entry Points`_ feature to load the dependencies. Add this code below to +``gino_fastapi_demo.main``:: + + import logging + from importlib.metadata import entry_points + + logger = logging.getLogger(__name__) + + def load_modules(app=None): + for ep in entry_points()["gino_fastapi_demo.modules"]: + logger.info("Loading module: %s", ep.name) + mod = ep.load() + if app: + init_app = getattr(mod, "init_app", None) + if init_app: + init_app(app) + +.. hint:: + + If you're running Python < 3.8, you'll need this `importlib-metadata backport + `_. + +And call it in our application factory: + +.. code-block:: diff + + def get_app(): + app = FastAPI(title="GINO FastAPI Demo") + db.init_app(app) + + load_modules(app) + return app + +Finally, define the entry points in ``pyproject.toml`` following the `Poetry document +for plugins `_: + +.. code-block:: toml + + [tool.poetry.plugins."gino_fastapi_demo.modules"] + "users" = "gino_fastapi_demo.views.users" + +Run ``poetry install`` again to activate the entry points - you may need to restart the +Uvicorn_ development server manually, as the reloader cannot capture the changes we made +to ``pyproject.toml``. + +Now you should be able to see the 3 new APIs on the Swagger UI. But none of them works, +because we still haven't created the database tables. + +.. |APIRouter| replace:: ``APIRouter`` +.. _APIRouter: https://fastapi.tiangolo.com/tutorial/bigger-applications/#apirouter +.. _inversion of control: https://en.wikipedia.org/wiki/Inversion_of_control +.. _Entry Points: https://docs.python.org/3/library/importlib.metadata.html#entry-points + + +Integrate with Alembic +---------------------- + +To get started with Alembic_, run this command in the project root directory: + +.. code-block:: console + + $ poetry run alembic init migrations + +.. image:: ../images/gino-fastapi-alembic.svg + :align: right + +This will generate a new directory ``migrations`` where Alembic_ will store database +migration revisions. At the same time, an ``alembic.ini`` file is created in the project +root directory. Let's simply add all of them to Git control. + +For Alembic_ to use our data models defined with GINO (and of course the database +config), we need to modify ``migrations/env.py`` to connect with the GINO instance: + +.. code-block:: diff + + # add your model's MetaData object here + # for 'autogenerate' support + # from myapp import mymodel + # target_metadata = mymodel.Base.metadata + -target_metadata = None + +from gino_fastapi_demo.config import DB_DSN + +from gino_fastapi_demo.main import db, load_modules + + + +load_modules() + +config.set_main_option("sqlalchemy.url", str(DB_DSN)) + +target_metadata = db + +Then create our first migration revision with: + +.. code-block:: console + + $ poetry run alembic revision --autogenerate -m 'add users table' + INFO [alembic.runtime.migration] Context impl PostgresqlImpl. + INFO [alembic.runtime.migration] Will assume transactional DDL. + INFO [alembic.autogenerate.compare] Detected added table 'users' + Generating migrations/versions/32c0feba61ea_add_users_table.py ... done + +The generated revision file should roughly look like this:: + + def upgrade(): + op.create_table( + "users", + sa.Column("id", sa.BigInteger(), nullable=False), + sa.Column("nickname", sa.Unicode(), nullable=True), + sa.PrimaryKeyConstraint("id"), + ) + + def downgrade(): + op.drop_table("users") + +.. hint:: + + Whenever there is a change to the database schema in the future, just modify the + GINO models and run ``alembic revision --autogenerate`` again to generate new + revisions to track the change. Remember to review the revision file - you may want + to adjust it. + +Eventually, let's apply this migration, by upgrading to the latest revision: + +.. code-block:: console + + $ poetry run alembic upgrade head + INFO [alembic.runtime.migration] Context impl PostgresqlImpl. + INFO [alembic.runtime.migration] Will assume transactional DDL. + INFO [alembic.runtime.migration] Running upgrade -> 32c0feba61ea, add users table + +Now all the APIs should be fully operational, try with the Swagger UI. + + +Write the Tests +--------------- + +In order not to break our development database with running tests, let's create a +separate database to run tests. Apply this change to ``gino_fastapi_demo.config``: + +.. code-block:: diff + + config = Config(".env") + + +TESTING = config("TESTING", cast=bool, default=False) + + DB_DRIVER = config("DB_DRIVER", default="postgresql") + DB_HOST = config("DB_HOST", default=None) + DB_PORT = config("DB_PORT", cast=int, default=None) + DB_USER = config("DB_USER", default=None) + DB_PASSWORD = config("DB_PASSWORD", cast=Secret, default=None) + DB_DATABASE = config("DB_DATABASE", default=None) + +if TESTING: + + if DB_DATABASE: + + DB_DATABASE += "_test" + + else: + + DB_DATABASE = "gino_fastapi_demo_test" + DB_DSN = config( + +.. hint:: + + You need to run ``createdb`` to actually create the database. If you have set + ``DB_DATABASE`` in ``.env`` - e.g. ``DB_DATABASE=mydb``, the name of the testing + database should be ``mydb_test``. Or else, ``gino_fastapi_demo_test``. + +Then, let's create our pytest_ fixture in ``tests/conftest.py``:: + + import pytest + from alembic.config import main + from starlette.config import environ + from starlette.testclient import TestClient + + environ["TESTING"] = "TRUE" + + @pytest.fixture + def client(): + from gino_fastapi_demo.main import db, get_app + + main(["--raiseerr", "upgrade", "head"]) + + with TestClient(get_app()) as client: + yield client + + main(["--raiseerr", "downgrade", "base"]) + +.. image:: ../images/gino-fastapi-tests.svg + :align: right + +This fixture creates all the database tables before running the test, yield a Starlette_ +|TestClient|_, and drop all the tables with all the data after the test to maintain a +clean environment for the next test. + +Here's a sample test in ``tests/test_users.py``:: + + import uuid + + def test_crud(client): + # create + nickname = str(uuid.uuid4()) + r = client.post("/users", json=dict(name=nickname)) + r.raise_for_status() + + # retrieve + url = f"/users/{r.json()['id']}" + assert client.get(url).json()["nickname"] == nickname + + # delete + client.delete(url).raise_for_status() + assert client.get(url).status_code == 404 + +Then run the test: + +.. code-block:: console + + $ poetry run pytest + =========================== test session starts =========================== + platform darwin -- Python 3.8.2, pytest-5.4.1, py-1.8.1, pluggy-0.13.1 + rootdir: gino-fastapi-demo + collected 1 item + + tests/test_users.py . [100%] + + ============================ 1 passed in 1.21s ============================ + +.. |TestClient| replace:: ``TestClient`` +.. _TestClient: https://www.starlette.io/testclient/ + + +Notes for Production +-------------------- + +Given the popularity of Docker/Kubernetes, we'll build a ``Dockerfile`` for our demo: + +.. code-block:: dockerfile + + FROM python:3.8-alpine as base + + FROM base as builder + RUN apk add --no-cache gcc musl-dev libffi-dev openssl-dev make postgresql-dev + RUN pip install poetry + COPY . /src/ + WORKDIR /src + RUN python -m venv /env && . /env/bin/activate && poetry install + + FROM base + RUN apk add --no-cache postgresql-libs + COPY --from=builder /env /env + COPY --from=builder /src /src + WORKDIR /src + CMD ["/env/bin/gunicorn", "gino_fastapi_demo.asgi:app", "-b", "0.0.0.0:80", "-k", "uvicorn.workers.UvicornWorker"] + +In this ``Dockerfile``, we used 2 phases to separate the building from the production +image to reduce target artifact size. Also, we are using Gunicorn_ with +|UvicornWorker|_ from Uvicorn_ as the worker class for best production reliability. + +Let's review what we have in the project. + +.. image:: ../images/gino-fastapi-layout.svg + :align: center + +This is the end of the tutorial to build a demo. Below is an incomplete checklist to +go live: + +* Set ``DB_RETRY_LIMIT`` to a larger number to allow staring the application server + before the database is fully ready. +* Implement the same retry logic in ``migrations/env.py`` so that Alembic_ gets the same + functionality. +* Enable ``DB_SSL`` if needed. +* Write a ``docker-compose.yml`` for other developers to get a quick taste or even use + it for development. +* Enable CI_, install ``pytest-cov`` and use ``--cov-fail-under`` to guarantee coverage. +* Integrate static code analysis tools and security/CVE checking tools. +* Automate Alembic_ upgrade properly - e.g. after new version is deployed. +* Be aware of the common security attacks like CSRF_, XSS_, etc. +* Write load tests. + +Again, the source code of the demo is available `here +`__, +and the source of this tutorial is `here +`__. +Please feel free to submit PRs to fix issues or add your thoughts. Happy hacking! + +.. |UvicornWorker| replace:: ``UvicornWorker`` +.. _UvicornWorker: https://www.uvicorn.org/deployment/#gunicorn +.. _CI: https://en.wikipedia.org/wiki/Continuous_integration +.. _CSRF: https://en.wikipedia.org/wiki/Cross-site_request_forgery +.. _XSS: https://en.wikipedia.org/wiki/Cross-site_scripting diff --git a/docs/en/1.1b2/_sources/tutorials/tutorial.rst.txt b/docs/en/1.1b2/_sources/tutorials/tutorial.rst.txt new file mode 100644 index 0000000..d9527f3 --- /dev/null +++ b/docs/en/1.1b2/_sources/tutorials/tutorial.rst.txt @@ -0,0 +1,436 @@ +GINO Basics +=========== + +This tutorial helps beginners to get started with the basic part of GINO. +Target audiences of this tutorial should have basic knowledge of: + +* RDBMS, especially PostgreSQL_ +* `Asynchronous programming in Python `_ + +Knowledge of SQLAlchemy_ is not required. + +.. _PostgreSQL: https://www.postgresql.org/ + + +Introduction +------------ + +Simply speaking, GINO helps you write and execute raw SQL in your asynchronous +application. Instead of interacting RDBMS directly with raw SQL, you can access +your data through friendly objective API. + +You may not need GINO, or else to say asynchronous database connection, because +it adds quite some complexity and risk to your stack, and it won't make your +code run faster, if not slower. Please read :doc:`/explanation/why` for more +information. + + +Installation +------------ + +To install GINO, run this command in your terminal: + +.. code-block:: console + + $ pip install gino + +This is the preferred method to install GINO, as it will always install the +most recent stable release. + +If you don't have `pip`_ installed, this `Python installation guide`_ can guide +you through the process. + +Alternatively, if you are using Poetry_ to manage your project dependencies, +you may want to run: + +.. code-block:: console + + $ poetry add gino + +.. _pip: https://pip.pypa.io +.. _Python installation guide: http://docs.python-guide.org/en/latest/starting/installation/ +.. _Poetry: https://python-poetry.org + + +Declare Models +-------------- + +First of all, we'll need a :class:`~gino.api.Gino` object, usually under the +name of ``db`` as a global variable:: + + from gino import Gino + + db = Gino() + +``db`` acts like a reference to the database, most database interactions will +go through it. + +"Model" is a basic concept in GINO, it is a Python class inherited from +:attr:`db.Model `. Each :class:`~gino.declarative.Model` +subclass maps to one table in the database, while each object of the class +represents one row in the table. This must feel familiar if ORM is not a +strange word to you. Now let's declare a model:: + + class User(db.Model): + __tablename__ = 'users' + + id = db.Column(db.Integer(), primary_key=True) + nickname = db.Column(db.Unicode(), default='noname') + +By declaring this ``User`` class, we are actually defining a database table +named ``users``, with two columns ``id`` and ``nickname``. Note that the fixed +:attr:`~gino.declarative.Model.__tablename__` property is required. GINO +suggests singular for model names, and plural for table names. Each +:class:`db.Column ` property defines one column for +the table, where its first parameter indicates the column type in database, +while the rest is for other column attributes or constraints. You can find a +mapping of database types to ``db`` types `here +`__ in the SQLAlchemy +documentation. + +.. note:: + + SQLAlchemy_ is a powerful ORM library for non-asynchronous programming in + Python, on top of which GINO is built. SQLAlchemy supports many popular + RDBMS including PostgreSQL and MySQL through different dialect + implementation, so that the same Python code can be compiled into different + SQL depending on the dialect you choose. GINO inherited this support too, + but for now there is only one dialect for PostgreSQL through asyncpg_. + +.. _asyncpg: https://github.com/MagicStack/asyncpg +.. _SQLAlchemy: https://www.sqlalchemy.org/ + +If you need constraints or indexes covering multiple columns these are also +defined using properties in model classes. The property names must be unique, +but are otherwise not used. Example:: + + class Booking(db.Model): + __tablename__ = 'bookings' + + day = db.Column(db.Date) + booker = db.Column(db.String) + room = db.Column(db.String) + + _pk = db.PrimaryKeyConstraint('day', 'booker', name='bookings_pkey') + _idx1 = db.Index('bookings_idx_day_room', 'day', 'room', unique=True) + _idx2 = db.Index('bookings_idx_booker_room', 'booker', 'room') + +It is also possible to define model constraints and indexes outside the model +class if that is preferred. For more details on constraints and indexes, see +`here `__ in the +SQLAlchemy documentation. + +Due to implementation limitations it is currently not allowed to specify +explicit constraints and indexes as direct attributes in classes that are meant +to be subclassed. The same is true for constraints and indexes specified +through the :attr:`~gino.declarative.Model.__table_args__` attribute. In order +to e.g. define constraints in mixin classes, +:func:`~gino.declarative.declared_attr` is required. Please feel free to read +more about it in its API documentation. + + +Get Connected +------------- + +The declaration only defined the mapping, it does not create the actual table +in the database. To do that, we need to get connected first. Let's create a +PostgreSQL database for this tutorial: + +.. code-block:: console + + $ createdb gino + +Then we tell our ``db`` object to connect to this database:: + + import asyncio + + async def main(): + await db.set_bind('postgresql://localhost/gino') + + asyncio.get_event_loop().run_until_complete(main()) + +If this runs successfully, then you are connected to the newly created database. +Here ``postgresql`` indicates the database dialect to use (the default driver +is ``asyncpg``, you can explicitly specify that with ``postgresql+asyncpg://``, +or simply ``asyncpg://``), ``localhost`` is where the server is, and ``gino`` +is the name of the database. Check `here +`__ for more +information about how to compose this database URL. + +.. note:: + + Under the hood :meth:`~gino.api.Gino.set_bind` calls + :func:`~gino.create_engine` and bind the engine to this ``db`` object. GINO + engine is similar to SQLAlchemy engine, but not identical. Because GINO + engine is asynchronous, while the other is not. Please refer to the API + reference of GINO for more information. + +Now that we are connected, let's create the table in database (in the same +``main()`` method):: + + await db.gino.create_all() + +.. warning:: + + It is :meth:`db.gino.create_all `, + not :meth:`db.create_all `, because + ``db`` is inherited from SQLAlchemy :class:`~sqlalchemy.schema.MetaData`, + and :meth:`db.create_all ` is from + SQLAlchemy using non-asynchronous methods, which doesn't work with the + bound GINO engine. + + In practice :meth:`~gino.schema.GinoSchemaVisitor.create_all` is usually + not an ideal solution. To manage database schema, tool like Alembic_ is + recommended, please see how to :doc:`/how-to/alembic`. + +If you want to explicitly disconnect from the database, you can do this:: + + await db.pop_bind().close() + +Let's review the code we have so far together in one piece before moving on:: + + import asyncio + from gino import Gino + + db = Gino() + + + class User(db.Model): + __tablename__ = 'users' + + id = db.Column(db.Integer(), primary_key=True) + nickname = db.Column(db.Unicode(), default='noname') + + + async def main(): + await db.set_bind('postgresql://localhost/gino') + await db.gino.create_all() + + # further code goes here + + await db.pop_bind().close() + + + asyncio.get_event_loop().run_until_complete(main()) + +.. _Alembic: https://bitbucket.org/zzzeek/alembic + + +CRUD Operations +--------------- + +In order to operate on the database, one of GINO's core features is to Create, +Retrieve, Update or Delete model objects, also known as the CRUD operations. + + +Create +^^^^^^ + +Let's start by creating a ``User``:: + + user = await User.create(nickname='fantix') + # This will cause GINO to execute this SQL with parameter 'fantix': + # INSERT INTO users (nickname) VALUES ($1) RETURNING users.id, users.nickname + +As mentioned previously, ``user`` object represents the newly created row in +the database. You can get the value of each columns by the declared column +properties on the object:: + + print(f'ID: {user.id}') # 1 + print(f'Nickname: {user.nickname}') # fantix + +It is also possible to create a model instance in-memory first, modify it, then +finally create it in the database:: + + user = User(nickname='fantix') + user.nickname += ' (founder)' + await user.create() + +Retrieve +^^^^^^^^ + +To retrieve a model object from database by primary key, you can use the class +method :meth:`~gino.crud.CRUDModel.get` on the model class. Now let's retrieve +the same row:: + + user = await User.get(1) + # SQL (parameter: 1): + # SELECT users.id, users.nickname FROM users WHERE users.id = $1 + +Normal SQL queries are done through a class property +:attr:`~gino.crud.CRUDModel.query`. For example, let's retrieve all ``User`` +objects from database as a list:: + + all_users = await db.all(User.query) + # SQL: + # SELECT users.id, users.nickname FROM users + +Alternatively, you can use the ``gino`` extension on +:attr:`~gino.crud.CRUDModel.query`. This has exactly the same effect as above:: + + all_users = await User.query.gino.all() + # SQL: + # SELECT users.id, users.nickname FROM users + +.. note:: + + ``User.query`` is actually a SQLAlchemy query, with its own + non-asynchronous execution methods. GINO added this ``gino`` extension on + all executable SQLAlchemy clause objects to conveniently execute them in + the asynchronous way, so that it is even not needed to import the ``db`` + reference for execution. + +Now let's add some filters. For example, find all users with ID lower than 10:: + + founding_users = await User.query.where(User.id < 10).gino.all() + # SQL (parameter: 10): + # SELECT users.id, users.nickname FROM users WHERE users.id < $1 + +Read more `here `__ +about writing queries, because the query object is exactly from SQLAlchemy core. + +.. warning:: + + Once you get a model object, it is purely in memory and fully detached from + the database. That means, if the row is externally updated, the object + values remain unchanged. Likewise, changes made to the object won't affect + the database values. + + Also, GINO keeps no track of model objects, therefore getting the same row + twice returns two different object with identical values. Modifying one + does not magically affect the other one. + + Different than traditional ORMs, the GINO model objects are more like + objective SQL results, rather than stateful ORM objects. In order to adapt + for asynchronous programming, GINO is designed to be that simple. That's + also why GINO Is Not ORM. + +Sometimes we want to get only one object, for example getting the user by name +when logging in. There's a shortcut for this scenario:: + + user = await User.query.where(User.nickname == 'fantix').gino.first() + # SQL (parameter: 'fantix'): + # SELECT users.id, users.nickname FROM users WHERE users.nickname = $1 + +If there is no user named "fantix" in database, ``user`` will be ``None``. + +And sometimes we may want to get a single value from database, getting the name +of user with ID 1 for example. Then we can use the +:meth:`~gino.crud.CRUDModel.select` class method:: + + name = await User.select('nickname').where(User.id == 1).gino.scalar() + # SQL (parameter: 1): + # SELECT users.nickname FROM users WHERE users.id = $1 + print(name) # fantix + +Or get the count of all users:: + + population = await db.func.count(User.id).gino.scalar() + # SQL: + # SELECT count(users.id) AS count_1 FROM users + print(population) # 17 for example + + +Update +^^^^^^ + +Then let's try to make some modifications. In this example we'll mixin some +retrieve operations we just tried. :: + + # create a new user + user = await User.create(nickname='fantix') + + # get its name + name = await User.select('nickname').where( + User.id == user.id).gino.scalar() + assert name == user.nickname # they are both 'fantix' before the update + + # modification here + await user.update(nickname='daisy').apply() + # SQL (parameters: 'daisy', 1): + # UPDATE users SET nickname=$1 WHERE users.id = $2 RETURNING users.nickname + print(user.nickname) # daisy + + # get its name again + name = await User.select('nickname').where( + User.id == user.id).gino.scalar() + print(name) # daisy + assert name == user.nickname # they are both 'daisy' after the update + +So :meth:`~gino.crud.CRUDModel.update` is the first GINO method we met so far +on model instance level. It accepts multiple keyword arguments, whose keys are +column names while values are the new value to update to. The following +:meth:`~gino.crud.UpdateRequest.apply` call makes the update happen in database. + +.. note:: + + GINO explicitly split the in-memory update and SQL update into two methods: + :meth:`~gino.crud.CRUDModel.update` and + :meth:`~gino.crud.UpdateRequest.apply`. :meth:`~gino.crud.CRUDModel.update` + will update the in-memory model object and return an + :class:`~gino.crud.UpdateRequest` object which contains all the + modifications. A following :meth:`~gino.crud.UpdateRequest.apply` on + :class:`~gino.crud.UpdateRequest` object will apply these recorded + modifications to database by executing a compiled SQL. + +.. tip:: + + :class:`~gino.crud.UpdateRequest` object has another method named + :meth:`~gino.crud.UpdateRequest.update` which works the same as the one + on model object, just that it combines the new modifications together with + the ones already recorded in current :class:`~gino.crud.UpdateRequest` + object, and it returns the same :class:`~gino.crud.UpdateRequest` object. + That means, you can chain the updates and end up with one + :meth:`~gino.crud.UpdateRequest.apply`, or make use of the + :class:`~gino.crud.UpdateRequest` object to combine several updates in a + batch. + +:meth:`~gino.crud.CRUDModel.update` on model object affects only the row +represented by the object. If you want to do update with wider condition, you +can use the :meth:`~gino.crud.CRUDModel.update` on model class level, with a +bit difference:: + + await User.update.values(nickname='Founding Member ' + User.nickname).where( + User.id < 10).gino.status() + # SQL (parameter: 'Founding Member ', 10): + # UPDATE users SET nickname=($1 || users.nickname) WHERE users.id < $2 + + name = await User.select('nickname').where( + User.id == 1).gino.scalar() + print(name) # Founding Member fantix + +There is no :class:`~gino.crud.UpdateRequest` here, everything is again +SQLAlchemy clause, its +`documentation `_ here for +your reference. + + +Delete +^^^^^^ + +At last. Deleting is similar to updating, but way simpler. :: + + + user = await User.create(nickname='fantix') + await user.delete() + # SQL (parameter: 1): + # DELETE FROM users WHERE users.id = $1 + print(await User.get(user.id)) # None + +.. hint:: + + Remember the model object is in memory? In the last :func:`print` + statement, even though the row is already deleted in database, the object + ``user`` still exists with its values untouched. + +Or mass deletion (never forget the where clause, unless you want to truncate +the whole table!!):: + + await User.delete.where(User.id > 10).gino.status() + # SQL (parameter: 10): + # DELETE FROM users WHERE users.id > $1 + + +With basic :doc:`/how-to/crud`, you can already make some amazing stuff with +GINO. This tutorial ends here, please find out more in detail from the rest of +this documentation, and have fun hacking! diff --git a/docs/en/1.1b2/_static/css/gino.css b/docs/en/1.1b2/_static/css/gino.css new file mode 100644 index 0000000..7f0f40b --- /dev/null +++ b/docs/en/1.1b2/_static/css/gino.css @@ -0,0 +1,826 @@ +html { + text-rendering: optimizeLegibility; + -webkit-font-smoothing: antialiased; + -moz-osx-font-smoothing: grayscale; + -webkit-tap-highlight-color: rgba(0, 0, 0, 0); + -webkit-text-size-adjust: 100%; + box-sizing: border-box; + font-family: 'Raleway', -apple-system, BlinkMacSystemFont, 'Segoe UI', + Roboto, 'Helvetica Neue', Arial, sans-serif; + font-size: 16px; +} + +body { + background-color: #F0F0F0; + font-weight: 500; +} + +a { + color: #3E6CDE; +} + +code, kbd, samp { + font-family: monospace; + background-color: #f8f8f8; + border: 1px solid #f0f0f0; + padding: 0 4px; + border-radius: 2px; +} + +.highlight .hll { + display: block; +} + +strong { + font-weight: 700; +} + +:root { + --v-primary-base: #212B73; + --v-secondary-base: #AD755C; + --v-accent-base: #EEF5FF; + --v-error: #FF5252; + --v-info: #BDC8F1; + --v-info-light: #3E6CDE; + --v-success: #4CAF50; + --v-success-light: rgba(76, 175, 80, 0.2); + --v-warning: #FFC107; + --v-warning-light: rgba(255, 193, 7, 0.2); + --v-border: #444b54; + --v-border-light: #c0cee1; +} + +nav { + background-color: rgba(33, 43, 115, 0.95); + -webkit-box-shadow: 0 2px 4px -1px rgba(0, 0, 0, .2), 0 4px 5px 0 rgba(0, 0, 0, .14), 0 1px 10px 0 rgba(0, 0, 0, .12); + box-shadow: 0 2px 4px -1px rgba(0, 0, 0, .2), 0 4px 5px 0 rgba(0, 0, 0, .14), 0 1px 10px 0 rgba(0, 0, 0, .12); +} + +.nav-wrapper { + padding: 4px 16px; + display: flex; + align-items: center; +} + +nav .brand-logo { + position: relative; + display: flex; + align-items: center; + left: 0; + -webkit-transform: none; + -moz-transform: none; + -ms-transform: none; + -o-transform: none; + transform: none; +} + +.breadcrumbs { + display: flex; + flex-wrap: nowrap; + overflow-x: scroll; + -ms-overflow-style: none; +} + +.breadcrumbs::-webkit-scrollbar { + display: none; +} + +.breadcrumbs .breadcrumb, +.breadcrumbs .breadcrumb::before { + content: '>'; + font-size: 16px; + white-space: nowrap; +} + + +.btn-flat { + display: flex; + align-items: center; + font-weight: 500; + margin-left: 22px; + text-decoration: none; + color: #fff; + padding: 14px; + font-size: 14px; + -webkit-transition: .2s; + transition: .2s; +} + +.btn-flat:hover { + color: #f8d230; + text-shadow: #f8d230 0 0 5px; +} + +a.brackets:before, +span.brackets:empty, +span.brackets > a:before{ + content: "["; +} + +a.brackets:after, +span.brackets > a:after { + content: "]"; +} + +a.footnote-reference { + vertical-align: super; + font-size: 0.8em; +} + +.footnote dt { + float: left; +} + +div.search { + position: relative; + display: flex; + align-items: center; + margin-right: 12px; +} + +div.search i { + position: absolute; + left: 10px; + transition: 0.3s; +} + +#search:focus + i { + color: var(--v-primary-base); +} + +#search { + flex: 0.1 1 192px; + background-color: rgba(255, 255, 255, 0.16); + border-radius: 28px; + height: 38px; + padding: 0 32px 0 42px; + margin: 0; + border: none; + transition: 0.3s; + color: rgba(255, 255, 255, 0.32); + font-size: 14px; +} + +#search:focus { + border: none; + background-color: #FFFFFF; + color: #000000; +} + +#search-results { + position: absolute; + left: 0; + right: -250px; + max-height: 61.8vh; + background-color: rgba(0, 0, 0, 0.8); + border-bottom-left-radius: 4px; + border-bottom-right-radius: 4px; + overflow: scroll; + top: 51px; + padding: 16px; +} + +#search-results li { + float: none; + line-height: 1.5; + font-size: 14px; +} + +#search-results li a { + color: #4E7CEE; + padding: 0; +} + +#search-results li .context { + padding: 0 0 24px 24px; +} +#search-results .highlighted { + color: #f8d230; +} + +.theme-dark { + color: #FFFFFF; +} + +.spacer { + flex-grow: 1; +} + +.img { + background-size: contain; + background-position: center; + background-repeat: no-repeat; +} + +.sidenav { + top: 64px; + z-index: 900; + box-shadow: none; + bottom: 0; + height: auto; +} + +.col.body { + padding: 0; +} + +#main-content { + padding: 0 24px; + background-color: white; +} + +.sidenav ul li:first-of-type { + display: none; +} + +.sidenav ul ul li:first-of-type { + display: block; +} + +.sidenav .caption { + font-size: 1.2em; + color: var(--v-primary-base); + padding: 16px 32px 0 48px; + position: relative; + font-weight: 600; +} + +.sidenav .caption::before { + position: absolute; + display: block; + content: " "; + width: 20px; + height: 20px; + left: 16px; + top: 20px; + background-size: contain; + background-repeat: no-repeat; + background-position: center center; +} + +.sidenav li > a { + font-size: 14px; + line-height: 14px; + padding: 12px 24px 12px 48px; + height: auto; +} + +.sidenav li li > a { + padding-left: 70px; +} + +.sidenav .caption:nth-of-type(1)::before { + background-image: url(../images/tutorials-icon.svg); +} +.sidenav .caption:nth-of-type(2)::before { + background-image: url(../images/how-to-icon.svg); +} +.sidenav .caption:nth-of-type(3)::before { + background-image: url(../images/explanation-logo.svg); +} +.sidenav .caption:nth-of-type(4)::before { + background-image: url(../images/reference-logo.svg); +} + +.sidenav a.current { + background-color: var(--v-accent-base); +} + +.github { + margin-left: 16px; + transition: 0.3s; +} + +.github:hover { + text-shadow: #FFFFFF 0 0 5px; +} + +.github i { + font-size: 40px; +} + +.right-nav.col { + padding: 0; +} + +.table-of-contents { + padding: 16px; + top: 64px; + bottom: 0; + overflow-y: auto; +} + +.table-of-contents li { + padding: 0; +} + +.table-of-contents > ul > li > a { + display: none; +} + +.table-of-contents > ul ul > li > a.active, +.table-of-contents > ul ul > li > a:hover { + padding-left: 14px; +} + +.table-of-contents > ul ul ul > li > a.active, +.table-of-contents > ul ul ul > li > a:hover { + padding-left: 30px; +} + +.table-of-contents > ul ul ul > li > a { + padding-left: 32px; +} + +.table-of-contents > ul ul ul ul > li > a.active, +.table-of-contents > ul ul ul ul > li > a:hover { + padding-left: 46px; +} + +.table-of-contents > ul ul ul ul > li > a { + padding-left: 48px; +} + +.table-of-contents a { + height: auto; + padding-top: 2px; + padding-bottom: 2px; +} + +.table-of-contents a.active, +.table-of-contents a:hover { + color: var(--v-primary-base); + border-left: 2px solid var(--v-primary-base); + font-weight: 500; +} + +.table-of-contents #version-selector hr { + margin-top: 48px; +} + +.table-of-contents #version-selector div { + margin-top: 16px; + color: #757575; +} + +.table-of-contents #version-selector a { + color: #757575; +} + +.table-of-contents .add-your-lang, +.table-of-contents .add-your-lang a, +.table-of-contents .add-your-lang a:active, +.table-of-contents .add-your-lang a:hover { + border-left: none; + font-size: 14px; + text-decoration: underline; + text-align: right; + margin-top: 8px; + color: #aaa; + font-weight: normal; +} + +.table-of-contents #version-selector span, +.table-of-contents #version-selector a, +.table-of-contents #version-selector a:active, +.table-of-contents #version-selector a:hover { + border-left: none; + padding: 8px; + margin-left: 16px; +} + +.table-of-contents #version-selector a:active, +.table-of-contents #version-selector a:hover { + color: var(--v-info-light); +} + +.table-of-contents #version-selector span { + color: var(--v-info-light); +} + +.version-warning { + border: 1px solid #757575; + background-color: #ffaaaa; + padding: 8px; +} + +h1 { + font-size: 32px; + margin: 32px 0 20px 0; + font-weight: 600; +} + +h2 { + font-size: 26px; + margin: 18px 0 12px 0; + font-weight: 600; +} + +h3 { + font-size: 22px; + margin: 17px 0 11px 0; + font-weight: 600; +} + +h4 { + font-size: 18px; + margin: 14px 0 9px 0; + font-weight: 600; +} + +h5 { + font-size: 16px; + margin: 13px 0 8px 0; + font-weight: 600; +} + +h6 { + font-size: 15px; + margin: 12px 0 7px 0; + font-weight: 600; +} + +a.headerlink { + padding-left: 8px; + visibility: hidden; + position: absolute; + font-family: sans-serif; +} + +:hover > a.headerlink { + visibility: visible; +} + +.section { + /*margin-top: -64px;*/ + /*padding-top: 64px;*/ +} + +.highlight { + background-color: rgba(0, 0, 0, 0.8); + clear: both; +} + +.highlight pre { + border: 1px solid var(--v-border-light); + padding: 1em; + font-size: 14px; + overflow-x: auto; +} + +.body li p { + margin: 0; +} + +.body ul li { + list-style-type: disc; + margin-left: 2rem; +} + +.body ul li li { + list-style-type: circle; +} + +.body ul li li li { + list-style-type: square; +} + +.admonition { + border-radius: 4px; + padding: 1px 1rem 40px; + box-shadow: #D1CECE 0 0 4px; + background-repeat: no-repeat; + background-position: 100% calc(100% + 20px); + background-size: 128px; +} + +.admonition-title { + font-size: 18px; + font-weight: 600; + color: #3E6CDE; +} + +.admonition-title:before { + content: " "; + display: inline-block; + width: 20px; + height: 20px; + margin: 0 8px -4px 0; + background-size: contain; + background-repeat: no-repeat; + background-position: center center; +} + +.admonition.note, +.admonition.seealso { + background-color: #F5FAFD; + background-image: url(../images/hmm.png); +} + +.admonition.note .admonition-title:before, +.admonition.seealso .admonition-title:before { + background-image: url(../images/icon-note.svg); +} + +.admonition.tip, +.admonition.hint { + background-color: #F5FDF6; + background-image: url(../images/aha.png); +} + +.admonition.tip { + background-image: url(../images/OK.png); +} + +.admonition.hint .admonition-title:before { + background-image: url(../images/icon-hint.svg); +} + +.admonition.warning { + background-color: #FDF5F5; + background-image: url(../images/fighting.png); +} + +.admonition.warning .admonition-title:before { + background-image: url(../images/icon-warning.svg); +} + +.admonition.tip .admonition-title:before { + background-image: url(../images/icon-info.svg); +} + +.body .section ul.boxed-nav { + list-style: none; + display: flex; + flex-wrap: wrap; + justify-content: space-between; + max-width: 700px; +} + +.body .section ul.boxed-nav li { + border-radius: 4px; + box-shadow: #D1CECE 0 0 4px; + padding: 10px; + margin: 25px 0 0; + width: 340px; + list-style: none; + color: #202A73; + font-weight: 500; + overflow: hidden; +} + +.body .section ul.boxed-nav li div { + background-color: #F4F7FC; + border-radius: 4px; + height: 110px; + padding: 30px 30px 0; + background-image: url(../images/box-bg-dec.svg); + background-repeat: no-repeat; + background-position: -15px -10px; +} + +.body .section ul.boxed-nav li:nth-of-type(3n) div { + background-image: url(../images/box-bg-dec-2.svg); +} + +.body .section ul.boxed-nav li:nth-of-type(3n+1) div { + background-image: url(../images/box-bg-dec-3.svg); +} + +.body .section ul.boxed-nav li a img { + width: 42px; + margin: 0 30px 30px 0; + float: left; +} + +.body .section ul.boxed-nav li p { + font-size: 18px; + color: #212B73; + line-height: 18px; + margin-bottom: 8px; +} + +.body .section ul.boxed-nav li p:nth-of-type(2) { + font-size: 14px; + word-break: break-word; +} + +.body .section ul.boxed-nav p a, +.body .section ul.boxed-nav p a:visited { + color: #212B73; +} + +p.divio { + position: absolute; + font-size: 0.8em; + color: #aaa; + margin-top: 40px; +} + +p.divio a, p.divio a:visited { + color: #aaa; +} + +.github-stars { + display: flex; + align-items: center; + padding: 0; + margin-left: 32px; + border-radius: 27px; + font-size: 14px; + font-weight: 500; +} + +.github-stars div { + border: 1px solid #fff; + line-height: 27px; + background-color: #1E2B78; + transition: 0.1s; + height: 29px; +} + +.github-stars div.left { + border-bottom-left-radius: 27px; + border-top-left-radius: 27px; + border-right: none; + padding: 0 7px 0 34px; + position: relative; +} + +.github-stars div.left .github-logo { + position: absolute; + height: 29px; + top: -1px; + left: -1px; +} + +.github-stars div.right { + border-bottom-right-radius: 27px; + border-top-right-radius: 27px; + padding: 0 7px 0 7px; + display: flex; + align-items: center; +} + +.github-stars div.right img { + height: 14px; + margin-right: 7px; +} + +.github-stars:hover { + color: white; + text-shadow: none; + box-shadow: #ffffff 0 0 5px; +} + +.btn-large.white img { + width: 32px; + height: 32px; + margin-top: 6px; +} + +.btn-large.white div { + color: #3E6CDE; + position: absolute; + bottom: 0; + width: 56px; + line-height: 18px; + font-size: 14px; + font-weight: 600; +} + +.sidenav-overlay { + z-index: 897; +} + +nav a.sidenav-trigger { + height: 24px; + margin: 16px 16px 16px 0; + display: flex; + flex-direction: column; + justify-content: space-around; +} +nav a.sidenav-trigger hr { + width: 24px; + margin: 0; + border: 0; + background-color: #fff; + height: 2px; +} + +.fixed-action-btn { + display: none; +} + +@media (min-width: 993px) { + main { + padding-left: 300px; + } + + #main-content { + padding: 0 48px; + margin: 16px; + border-radius: 4px; + } + + .admonition { + margin: 1.5rem 2rem; + padding: 1px 3rem 40px; + } + + img.align-center { + max-width: 100%; + display: block; + margin: 0 auto; + } + + img.align-left { + max-width: 100%; + float: left; + margin: 0 2rem 1.5rem 0; + } + + img.align-right { + max-width: 100%; + float: right; + margin: 0 0 1.5rem 2rem; + } + + .table-of-contents { + width: calc(25vw - 75px); + } + + p.divio { + margin-left: -47px; + } + + .btn-flat { + margin-left: 22px; + padding: 14px; + } + + .sidenav { + top: 64px; + } + + nav a.sidenav-trigger { + display: none; + } +} + +@media (max-width: 992px) { + img.align-left, + img.align-center, + img.align-right { + display: block; + margin: 1.5rem auto; + max-width: 100%; + } + + .admonition { + overflow: scroll; + } + + #main-content { + padding-bottom: 56px; + } + + #main-content p { + overflow-x: scroll; + } + + main > .row { + margin-bottom: 0; + } + + .breadcrumbs { + display: none; + } + + .btn-flat { + margin-left: 10px; + padding: 5px; + } +} + +@media (max-width: 740px) { + #search-container { + display: none; + } +} + +@media (max-width: 600px) { + .sidenav { + top: 56px; + } + + .fixed-action-btn { + display: block; + } +} + +@media (max-width: 510px) { + .github-stars { + display: none; + } +} diff --git a/docs/en/1.1b2/_static/css/materialize.min.css b/docs/en/1.1b2/_static/css/materialize.min.css new file mode 100644 index 0000000..74b1741 --- /dev/null +++ b/docs/en/1.1b2/_static/css/materialize.min.css @@ -0,0 +1,13 @@ +/*! + * Materialize v1.0.0 (http://materializecss.com) + * Copyright 2014-2017 Materialize + * MIT License (https://raw.githubusercontent.com/Dogfalo/materialize/master/LICENSE) + */ +.materialize-red{background-color:#e51c23 !important}.materialize-red-text{color:#e51c23 !important}.materialize-red.lighten-5{background-color:#fdeaeb !important}.materialize-red-text.text-lighten-5{color:#fdeaeb !important}.materialize-red.lighten-4{background-color:#f8c1c3 !important}.materialize-red-text.text-lighten-4{color:#f8c1c3 !important}.materialize-red.lighten-3{background-color:#f3989b !important}.materialize-red-text.text-lighten-3{color:#f3989b !important}.materialize-red.lighten-2{background-color:#ee6e73 !important}.materialize-red-text.text-lighten-2{color:#ee6e73 !important}.materialize-red.lighten-1{background-color:#ea454b !important}.materialize-red-text.text-lighten-1{color:#ea454b !important}.materialize-red.darken-1{background-color:#d0181e !important}.materialize-red-text.text-darken-1{color:#d0181e !important}.materialize-red.darken-2{background-color:#b9151b !important}.materialize-red-text.text-darken-2{color:#b9151b !important}.materialize-red.darken-3{background-color:#a21318 !important}.materialize-red-text.text-darken-3{color:#a21318 !important}.materialize-red.darken-4{background-color:#8b1014 !important}.materialize-red-text.text-darken-4{color:#8b1014 !important}.red{background-color:#F44336 !important}.red-text{color:#F44336 !important}.red.lighten-5{background-color:#FFEBEE !important}.red-text.text-lighten-5{color:#FFEBEE !important}.red.lighten-4{background-color:#FFCDD2 !important}.red-text.text-lighten-4{color:#FFCDD2 !important}.red.lighten-3{background-color:#EF9A9A !important}.red-text.text-lighten-3{color:#EF9A9A !important}.red.lighten-2{background-color:#E57373 !important}.red-text.text-lighten-2{color:#E57373 !important}.red.lighten-1{background-color:#EF5350 !important}.red-text.text-lighten-1{color:#EF5350 !important}.red.darken-1{background-color:#E53935 !important}.red-text.text-darken-1{color:#E53935 !important}.red.darken-2{background-color:#D32F2F !important}.red-text.text-darken-2{color:#D32F2F !important}.red.darken-3{background-color:#C62828 !important}.red-text.text-darken-3{color:#C62828 !important}.red.darken-4{background-color:#B71C1C !important}.red-text.text-darken-4{color:#B71C1C !important}.red.accent-1{background-color:#FF8A80 !important}.red-text.text-accent-1{color:#FF8A80 !important}.red.accent-2{background-color:#FF5252 !important}.red-text.text-accent-2{color:#FF5252 !important}.red.accent-3{background-color:#FF1744 !important}.red-text.text-accent-3{color:#FF1744 !important}.red.accent-4{background-color:#D50000 !important}.red-text.text-accent-4{color:#D50000 !important}.pink{background-color:#e91e63 !important}.pink-text{color:#e91e63 !important}.pink.lighten-5{background-color:#fce4ec !important}.pink-text.text-lighten-5{color:#fce4ec !important}.pink.lighten-4{background-color:#f8bbd0 !important}.pink-text.text-lighten-4{color:#f8bbd0 !important}.pink.lighten-3{background-color:#f48fb1 !important}.pink-text.text-lighten-3{color:#f48fb1 !important}.pink.lighten-2{background-color:#f06292 !important}.pink-text.text-lighten-2{color:#f06292 !important}.pink.lighten-1{background-color:#ec407a !important}.pink-text.text-lighten-1{color:#ec407a !important}.pink.darken-1{background-color:#d81b60 !important}.pink-text.text-darken-1{color:#d81b60 !important}.pink.darken-2{background-color:#c2185b !important}.pink-text.text-darken-2{color:#c2185b !important}.pink.darken-3{background-color:#ad1457 !important}.pink-text.text-darken-3{color:#ad1457 !important}.pink.darken-4{background-color:#880e4f !important}.pink-text.text-darken-4{color:#880e4f !important}.pink.accent-1{background-color:#ff80ab !important}.pink-text.text-accent-1{color:#ff80ab !important}.pink.accent-2{background-color:#ff4081 !important}.pink-text.text-accent-2{color:#ff4081 !important}.pink.accent-3{background-color:#f50057 !important}.pink-text.text-accent-3{color:#f50057 !important}.pink.accent-4{background-color:#c51162 !important}.pink-text.text-accent-4{color:#c51162 !important}.purple{background-color:#9c27b0 !important}.purple-text{color:#9c27b0 !important}.purple.lighten-5{background-color:#f3e5f5 !important}.purple-text.text-lighten-5{color:#f3e5f5 !important}.purple.lighten-4{background-color:#e1bee7 !important}.purple-text.text-lighten-4{color:#e1bee7 !important}.purple.lighten-3{background-color:#ce93d8 !important}.purple-text.text-lighten-3{color:#ce93d8 !important}.purple.lighten-2{background-color:#ba68c8 !important}.purple-text.text-lighten-2{color:#ba68c8 !important}.purple.lighten-1{background-color:#ab47bc !important}.purple-text.text-lighten-1{color:#ab47bc !important}.purple.darken-1{background-color:#8e24aa !important}.purple-text.text-darken-1{color:#8e24aa !important}.purple.darken-2{background-color:#7b1fa2 !important}.purple-text.text-darken-2{color:#7b1fa2 !important}.purple.darken-3{background-color:#6a1b9a !important}.purple-text.text-darken-3{color:#6a1b9a !important}.purple.darken-4{background-color:#4a148c !important}.purple-text.text-darken-4{color:#4a148c !important}.purple.accent-1{background-color:#ea80fc !important}.purple-text.text-accent-1{color:#ea80fc !important}.purple.accent-2{background-color:#e040fb !important}.purple-text.text-accent-2{color:#e040fb !important}.purple.accent-3{background-color:#d500f9 !important}.purple-text.text-accent-3{color:#d500f9 !important}.purple.accent-4{background-color:#a0f !important}.purple-text.text-accent-4{color:#a0f !important}.deep-purple{background-color:#673ab7 !important}.deep-purple-text{color:#673ab7 !important}.deep-purple.lighten-5{background-color:#ede7f6 !important}.deep-purple-text.text-lighten-5{color:#ede7f6 !important}.deep-purple.lighten-4{background-color:#d1c4e9 !important}.deep-purple-text.text-lighten-4{color:#d1c4e9 !important}.deep-purple.lighten-3{background-color:#b39ddb !important}.deep-purple-text.text-lighten-3{color:#b39ddb !important}.deep-purple.lighten-2{background-color:#9575cd !important}.deep-purple-text.text-lighten-2{color:#9575cd !important}.deep-purple.lighten-1{background-color:#7e57c2 !important}.deep-purple-text.text-lighten-1{color:#7e57c2 !important}.deep-purple.darken-1{background-color:#5e35b1 !important}.deep-purple-text.text-darken-1{color:#5e35b1 !important}.deep-purple.darken-2{background-color:#512da8 !important}.deep-purple-text.text-darken-2{color:#512da8 !important}.deep-purple.darken-3{background-color:#4527a0 !important}.deep-purple-text.text-darken-3{color:#4527a0 !important}.deep-purple.darken-4{background-color:#311b92 !important}.deep-purple-text.text-darken-4{color:#311b92 !important}.deep-purple.accent-1{background-color:#b388ff !important}.deep-purple-text.text-accent-1{color:#b388ff !important}.deep-purple.accent-2{background-color:#7c4dff !important}.deep-purple-text.text-accent-2{color:#7c4dff !important}.deep-purple.accent-3{background-color:#651fff !important}.deep-purple-text.text-accent-3{color:#651fff !important}.deep-purple.accent-4{background-color:#6200ea !important}.deep-purple-text.text-accent-4{color:#6200ea !important}.indigo{background-color:#3f51b5 !important}.indigo-text{color:#3f51b5 !important}.indigo.lighten-5{background-color:#e8eaf6 !important}.indigo-text.text-lighten-5{color:#e8eaf6 !important}.indigo.lighten-4{background-color:#c5cae9 !important}.indigo-text.text-lighten-4{color:#c5cae9 !important}.indigo.lighten-3{background-color:#9fa8da !important}.indigo-text.text-lighten-3{color:#9fa8da !important}.indigo.lighten-2{background-color:#7986cb !important}.indigo-text.text-lighten-2{color:#7986cb !important}.indigo.lighten-1{background-color:#5c6bc0 !important}.indigo-text.text-lighten-1{color:#5c6bc0 !important}.indigo.darken-1{background-color:#3949ab !important}.indigo-text.text-darken-1{color:#3949ab !important}.indigo.darken-2{background-color:#303f9f !important}.indigo-text.text-darken-2{color:#303f9f !important}.indigo.darken-3{background-color:#283593 !important}.indigo-text.text-darken-3{color:#283593 !important}.indigo.darken-4{background-color:#1a237e !important}.indigo-text.text-darken-4{color:#1a237e !important}.indigo.accent-1{background-color:#8c9eff !important}.indigo-text.text-accent-1{color:#8c9eff !important}.indigo.accent-2{background-color:#536dfe !important}.indigo-text.text-accent-2{color:#536dfe !important}.indigo.accent-3{background-color:#3d5afe !important}.indigo-text.text-accent-3{color:#3d5afe !important}.indigo.accent-4{background-color:#304ffe !important}.indigo-text.text-accent-4{color:#304ffe !important}.blue{background-color:#2196F3 !important}.blue-text{color:#2196F3 !important}.blue.lighten-5{background-color:#E3F2FD !important}.blue-text.text-lighten-5{color:#E3F2FD !important}.blue.lighten-4{background-color:#BBDEFB !important}.blue-text.text-lighten-4{color:#BBDEFB !important}.blue.lighten-3{background-color:#90CAF9 !important}.blue-text.text-lighten-3{color:#90CAF9 !important}.blue.lighten-2{background-color:#64B5F6 !important}.blue-text.text-lighten-2{color:#64B5F6 !important}.blue.lighten-1{background-color:#42A5F5 !important}.blue-text.text-lighten-1{color:#42A5F5 !important}.blue.darken-1{background-color:#1E88E5 !important}.blue-text.text-darken-1{color:#1E88E5 !important}.blue.darken-2{background-color:#1976D2 !important}.blue-text.text-darken-2{color:#1976D2 !important}.blue.darken-3{background-color:#1565C0 !important}.blue-text.text-darken-3{color:#1565C0 !important}.blue.darken-4{background-color:#0D47A1 !important}.blue-text.text-darken-4{color:#0D47A1 !important}.blue.accent-1{background-color:#82B1FF !important}.blue-text.text-accent-1{color:#82B1FF !important}.blue.accent-2{background-color:#448AFF !important}.blue-text.text-accent-2{color:#448AFF !important}.blue.accent-3{background-color:#2979FF !important}.blue-text.text-accent-3{color:#2979FF !important}.blue.accent-4{background-color:#2962FF !important}.blue-text.text-accent-4{color:#2962FF !important}.light-blue{background-color:#03a9f4 !important}.light-blue-text{color:#03a9f4 !important}.light-blue.lighten-5{background-color:#e1f5fe !important}.light-blue-text.text-lighten-5{color:#e1f5fe !important}.light-blue.lighten-4{background-color:#b3e5fc !important}.light-blue-text.text-lighten-4{color:#b3e5fc !important}.light-blue.lighten-3{background-color:#81d4fa !important}.light-blue-text.text-lighten-3{color:#81d4fa !important}.light-blue.lighten-2{background-color:#4fc3f7 !important}.light-blue-text.text-lighten-2{color:#4fc3f7 !important}.light-blue.lighten-1{background-color:#29b6f6 !important}.light-blue-text.text-lighten-1{color:#29b6f6 !important}.light-blue.darken-1{background-color:#039be5 !important}.light-blue-text.text-darken-1{color:#039be5 !important}.light-blue.darken-2{background-color:#0288d1 !important}.light-blue-text.text-darken-2{color:#0288d1 !important}.light-blue.darken-3{background-color:#0277bd !important}.light-blue-text.text-darken-3{color:#0277bd !important}.light-blue.darken-4{background-color:#01579b !important}.light-blue-text.text-darken-4{color:#01579b !important}.light-blue.accent-1{background-color:#80d8ff !important}.light-blue-text.text-accent-1{color:#80d8ff !important}.light-blue.accent-2{background-color:#40c4ff !important}.light-blue-text.text-accent-2{color:#40c4ff !important}.light-blue.accent-3{background-color:#00b0ff !important}.light-blue-text.text-accent-3{color:#00b0ff !important}.light-blue.accent-4{background-color:#0091ea !important}.light-blue-text.text-accent-4{color:#0091ea !important}.cyan{background-color:#00bcd4 !important}.cyan-text{color:#00bcd4 !important}.cyan.lighten-5{background-color:#e0f7fa !important}.cyan-text.text-lighten-5{color:#e0f7fa !important}.cyan.lighten-4{background-color:#b2ebf2 !important}.cyan-text.text-lighten-4{color:#b2ebf2 !important}.cyan.lighten-3{background-color:#80deea !important}.cyan-text.text-lighten-3{color:#80deea !important}.cyan.lighten-2{background-color:#4dd0e1 !important}.cyan-text.text-lighten-2{color:#4dd0e1 !important}.cyan.lighten-1{background-color:#26c6da !important}.cyan-text.text-lighten-1{color:#26c6da !important}.cyan.darken-1{background-color:#00acc1 !important}.cyan-text.text-darken-1{color:#00acc1 !important}.cyan.darken-2{background-color:#0097a7 !important}.cyan-text.text-darken-2{color:#0097a7 !important}.cyan.darken-3{background-color:#00838f !important}.cyan-text.text-darken-3{color:#00838f !important}.cyan.darken-4{background-color:#006064 !important}.cyan-text.text-darken-4{color:#006064 !important}.cyan.accent-1{background-color:#84ffff !important}.cyan-text.text-accent-1{color:#84ffff !important}.cyan.accent-2{background-color:#18ffff !important}.cyan-text.text-accent-2{color:#18ffff !important}.cyan.accent-3{background-color:#00e5ff !important}.cyan-text.text-accent-3{color:#00e5ff !important}.cyan.accent-4{background-color:#00b8d4 !important}.cyan-text.text-accent-4{color:#00b8d4 !important}.teal{background-color:#009688 !important}.teal-text{color:#009688 !important}.teal.lighten-5{background-color:#e0f2f1 !important}.teal-text.text-lighten-5{color:#e0f2f1 !important}.teal.lighten-4{background-color:#b2dfdb !important}.teal-text.text-lighten-4{color:#b2dfdb !important}.teal.lighten-3{background-color:#80cbc4 !important}.teal-text.text-lighten-3{color:#80cbc4 !important}.teal.lighten-2{background-color:#4db6ac !important}.teal-text.text-lighten-2{color:#4db6ac !important}.teal.lighten-1{background-color:#26a69a !important}.teal-text.text-lighten-1{color:#26a69a !important}.teal.darken-1{background-color:#00897b !important}.teal-text.text-darken-1{color:#00897b !important}.teal.darken-2{background-color:#00796b !important}.teal-text.text-darken-2{color:#00796b !important}.teal.darken-3{background-color:#00695c !important}.teal-text.text-darken-3{color:#00695c !important}.teal.darken-4{background-color:#004d40 !important}.teal-text.text-darken-4{color:#004d40 !important}.teal.accent-1{background-color:#a7ffeb !important}.teal-text.text-accent-1{color:#a7ffeb !important}.teal.accent-2{background-color:#64ffda !important}.teal-text.text-accent-2{color:#64ffda !important}.teal.accent-3{background-color:#1de9b6 !important}.teal-text.text-accent-3{color:#1de9b6 !important}.teal.accent-4{background-color:#00bfa5 !important}.teal-text.text-accent-4{color:#00bfa5 !important}.green{background-color:#4CAF50 !important}.green-text{color:#4CAF50 !important}.green.lighten-5{background-color:#E8F5E9 !important}.green-text.text-lighten-5{color:#E8F5E9 !important}.green.lighten-4{background-color:#C8E6C9 !important}.green-text.text-lighten-4{color:#C8E6C9 !important}.green.lighten-3{background-color:#A5D6A7 !important}.green-text.text-lighten-3{color:#A5D6A7 !important}.green.lighten-2{background-color:#81C784 !important}.green-text.text-lighten-2{color:#81C784 !important}.green.lighten-1{background-color:#66BB6A !important}.green-text.text-lighten-1{color:#66BB6A !important}.green.darken-1{background-color:#43A047 !important}.green-text.text-darken-1{color:#43A047 !important}.green.darken-2{background-color:#388E3C !important}.green-text.text-darken-2{color:#388E3C !important}.green.darken-3{background-color:#2E7D32 !important}.green-text.text-darken-3{color:#2E7D32 !important}.green.darken-4{background-color:#1B5E20 !important}.green-text.text-darken-4{color:#1B5E20 !important}.green.accent-1{background-color:#B9F6CA !important}.green-text.text-accent-1{color:#B9F6CA !important}.green.accent-2{background-color:#69F0AE !important}.green-text.text-accent-2{color:#69F0AE !important}.green.accent-3{background-color:#00E676 !important}.green-text.text-accent-3{color:#00E676 !important}.green.accent-4{background-color:#00C853 !important}.green-text.text-accent-4{color:#00C853 !important}.light-green{background-color:#8bc34a !important}.light-green-text{color:#8bc34a !important}.light-green.lighten-5{background-color:#f1f8e9 !important}.light-green-text.text-lighten-5{color:#f1f8e9 !important}.light-green.lighten-4{background-color:#dcedc8 !important}.light-green-text.text-lighten-4{color:#dcedc8 !important}.light-green.lighten-3{background-color:#c5e1a5 !important}.light-green-text.text-lighten-3{color:#c5e1a5 !important}.light-green.lighten-2{background-color:#aed581 !important}.light-green-text.text-lighten-2{color:#aed581 !important}.light-green.lighten-1{background-color:#9ccc65 !important}.light-green-text.text-lighten-1{color:#9ccc65 !important}.light-green.darken-1{background-color:#7cb342 !important}.light-green-text.text-darken-1{color:#7cb342 !important}.light-green.darken-2{background-color:#689f38 !important}.light-green-text.text-darken-2{color:#689f38 !important}.light-green.darken-3{background-color:#558b2f !important}.light-green-text.text-darken-3{color:#558b2f !important}.light-green.darken-4{background-color:#33691e !important}.light-green-text.text-darken-4{color:#33691e !important}.light-green.accent-1{background-color:#ccff90 !important}.light-green-text.text-accent-1{color:#ccff90 !important}.light-green.accent-2{background-color:#b2ff59 !important}.light-green-text.text-accent-2{color:#b2ff59 !important}.light-green.accent-3{background-color:#76ff03 !important}.light-green-text.text-accent-3{color:#76ff03 !important}.light-green.accent-4{background-color:#64dd17 !important}.light-green-text.text-accent-4{color:#64dd17 !important}.lime{background-color:#cddc39 !important}.lime-text{color:#cddc39 !important}.lime.lighten-5{background-color:#f9fbe7 !important}.lime-text.text-lighten-5{color:#f9fbe7 !important}.lime.lighten-4{background-color:#f0f4c3 !important}.lime-text.text-lighten-4{color:#f0f4c3 !important}.lime.lighten-3{background-color:#e6ee9c !important}.lime-text.text-lighten-3{color:#e6ee9c !important}.lime.lighten-2{background-color:#dce775 !important}.lime-text.text-lighten-2{color:#dce775 !important}.lime.lighten-1{background-color:#d4e157 !important}.lime-text.text-lighten-1{color:#d4e157 !important}.lime.darken-1{background-color:#c0ca33 !important}.lime-text.text-darken-1{color:#c0ca33 !important}.lime.darken-2{background-color:#afb42b !important}.lime-text.text-darken-2{color:#afb42b !important}.lime.darken-3{background-color:#9e9d24 !important}.lime-text.text-darken-3{color:#9e9d24 !important}.lime.darken-4{background-color:#827717 !important}.lime-text.text-darken-4{color:#827717 !important}.lime.accent-1{background-color:#f4ff81 !important}.lime-text.text-accent-1{color:#f4ff81 !important}.lime.accent-2{background-color:#eeff41 !important}.lime-text.text-accent-2{color:#eeff41 !important}.lime.accent-3{background-color:#c6ff00 !important}.lime-text.text-accent-3{color:#c6ff00 !important}.lime.accent-4{background-color:#aeea00 !important}.lime-text.text-accent-4{color:#aeea00 !important}.yellow{background-color:#ffeb3b !important}.yellow-text{color:#ffeb3b !important}.yellow.lighten-5{background-color:#fffde7 !important}.yellow-text.text-lighten-5{color:#fffde7 !important}.yellow.lighten-4{background-color:#fff9c4 !important}.yellow-text.text-lighten-4{color:#fff9c4 !important}.yellow.lighten-3{background-color:#fff59d !important}.yellow-text.text-lighten-3{color:#fff59d !important}.yellow.lighten-2{background-color:#fff176 !important}.yellow-text.text-lighten-2{color:#fff176 !important}.yellow.lighten-1{background-color:#ffee58 !important}.yellow-text.text-lighten-1{color:#ffee58 !important}.yellow.darken-1{background-color:#fdd835 !important}.yellow-text.text-darken-1{color:#fdd835 !important}.yellow.darken-2{background-color:#fbc02d !important}.yellow-text.text-darken-2{color:#fbc02d !important}.yellow.darken-3{background-color:#f9a825 !important}.yellow-text.text-darken-3{color:#f9a825 !important}.yellow.darken-4{background-color:#f57f17 !important}.yellow-text.text-darken-4{color:#f57f17 !important}.yellow.accent-1{background-color:#ffff8d !important}.yellow-text.text-accent-1{color:#ffff8d !important}.yellow.accent-2{background-color:#ff0 !important}.yellow-text.text-accent-2{color:#ff0 !important}.yellow.accent-3{background-color:#ffea00 !important}.yellow-text.text-accent-3{color:#ffea00 !important}.yellow.accent-4{background-color:#ffd600 !important}.yellow-text.text-accent-4{color:#ffd600 !important}.amber{background-color:#ffc107 !important}.amber-text{color:#ffc107 !important}.amber.lighten-5{background-color:#fff8e1 !important}.amber-text.text-lighten-5{color:#fff8e1 !important}.amber.lighten-4{background-color:#ffecb3 !important}.amber-text.text-lighten-4{color:#ffecb3 !important}.amber.lighten-3{background-color:#ffe082 !important}.amber-text.text-lighten-3{color:#ffe082 !important}.amber.lighten-2{background-color:#ffd54f !important}.amber-text.text-lighten-2{color:#ffd54f !important}.amber.lighten-1{background-color:#ffca28 !important}.amber-text.text-lighten-1{color:#ffca28 !important}.amber.darken-1{background-color:#ffb300 !important}.amber-text.text-darken-1{color:#ffb300 !important}.amber.darken-2{background-color:#ffa000 !important}.amber-text.text-darken-2{color:#ffa000 !important}.amber.darken-3{background-color:#ff8f00 !important}.amber-text.text-darken-3{color:#ff8f00 !important}.amber.darken-4{background-color:#ff6f00 !important}.amber-text.text-darken-4{color:#ff6f00 !important}.amber.accent-1{background-color:#ffe57f !important}.amber-text.text-accent-1{color:#ffe57f !important}.amber.accent-2{background-color:#ffd740 !important}.amber-text.text-accent-2{color:#ffd740 !important}.amber.accent-3{background-color:#ffc400 !important}.amber-text.text-accent-3{color:#ffc400 !important}.amber.accent-4{background-color:#ffab00 !important}.amber-text.text-accent-4{color:#ffab00 !important}.orange{background-color:#ff9800 !important}.orange-text{color:#ff9800 !important}.orange.lighten-5{background-color:#fff3e0 !important}.orange-text.text-lighten-5{color:#fff3e0 !important}.orange.lighten-4{background-color:#ffe0b2 !important}.orange-text.text-lighten-4{color:#ffe0b2 !important}.orange.lighten-3{background-color:#ffcc80 !important}.orange-text.text-lighten-3{color:#ffcc80 !important}.orange.lighten-2{background-color:#ffb74d !important}.orange-text.text-lighten-2{color:#ffb74d !important}.orange.lighten-1{background-color:#ffa726 !important}.orange-text.text-lighten-1{color:#ffa726 !important}.orange.darken-1{background-color:#fb8c00 !important}.orange-text.text-darken-1{color:#fb8c00 !important}.orange.darken-2{background-color:#f57c00 !important}.orange-text.text-darken-2{color:#f57c00 !important}.orange.darken-3{background-color:#ef6c00 !important}.orange-text.text-darken-3{color:#ef6c00 !important}.orange.darken-4{background-color:#e65100 !important}.orange-text.text-darken-4{color:#e65100 !important}.orange.accent-1{background-color:#ffd180 !important}.orange-text.text-accent-1{color:#ffd180 !important}.orange.accent-2{background-color:#ffab40 !important}.orange-text.text-accent-2{color:#ffab40 !important}.orange.accent-3{background-color:#ff9100 !important}.orange-text.text-accent-3{color:#ff9100 !important}.orange.accent-4{background-color:#ff6d00 !important}.orange-text.text-accent-4{color:#ff6d00 !important}.deep-orange{background-color:#ff5722 !important}.deep-orange-text{color:#ff5722 !important}.deep-orange.lighten-5{background-color:#fbe9e7 !important}.deep-orange-text.text-lighten-5{color:#fbe9e7 !important}.deep-orange.lighten-4{background-color:#ffccbc !important}.deep-orange-text.text-lighten-4{color:#ffccbc !important}.deep-orange.lighten-3{background-color:#ffab91 !important}.deep-orange-text.text-lighten-3{color:#ffab91 !important}.deep-orange.lighten-2{background-color:#ff8a65 !important}.deep-orange-text.text-lighten-2{color:#ff8a65 !important}.deep-orange.lighten-1{background-color:#ff7043 !important}.deep-orange-text.text-lighten-1{color:#ff7043 !important}.deep-orange.darken-1{background-color:#f4511e !important}.deep-orange-text.text-darken-1{color:#f4511e !important}.deep-orange.darken-2{background-color:#e64a19 !important}.deep-orange-text.text-darken-2{color:#e64a19 !important}.deep-orange.darken-3{background-color:#d84315 !important}.deep-orange-text.text-darken-3{color:#d84315 !important}.deep-orange.darken-4{background-color:#bf360c !important}.deep-orange-text.text-darken-4{color:#bf360c !important}.deep-orange.accent-1{background-color:#ff9e80 !important}.deep-orange-text.text-accent-1{color:#ff9e80 !important}.deep-orange.accent-2{background-color:#ff6e40 !important}.deep-orange-text.text-accent-2{color:#ff6e40 !important}.deep-orange.accent-3{background-color:#ff3d00 !important}.deep-orange-text.text-accent-3{color:#ff3d00 !important}.deep-orange.accent-4{background-color:#dd2c00 !important}.deep-orange-text.text-accent-4{color:#dd2c00 !important}.brown{background-color:#795548 !important}.brown-text{color:#795548 !important}.brown.lighten-5{background-color:#efebe9 !important}.brown-text.text-lighten-5{color:#efebe9 !important}.brown.lighten-4{background-color:#d7ccc8 !important}.brown-text.text-lighten-4{color:#d7ccc8 !important}.brown.lighten-3{background-color:#bcaaa4 !important}.brown-text.text-lighten-3{color:#bcaaa4 !important}.brown.lighten-2{background-color:#a1887f !important}.brown-text.text-lighten-2{color:#a1887f !important}.brown.lighten-1{background-color:#8d6e63 !important}.brown-text.text-lighten-1{color:#8d6e63 !important}.brown.darken-1{background-color:#6d4c41 !important}.brown-text.text-darken-1{color:#6d4c41 !important}.brown.darken-2{background-color:#5d4037 !important}.brown-text.text-darken-2{color:#5d4037 !important}.brown.darken-3{background-color:#4e342e !important}.brown-text.text-darken-3{color:#4e342e !important}.brown.darken-4{background-color:#3e2723 !important}.brown-text.text-darken-4{color:#3e2723 !important}.blue-grey{background-color:#607d8b !important}.blue-grey-text{color:#607d8b !important}.blue-grey.lighten-5{background-color:#eceff1 !important}.blue-grey-text.text-lighten-5{color:#eceff1 !important}.blue-grey.lighten-4{background-color:#cfd8dc !important}.blue-grey-text.text-lighten-4{color:#cfd8dc !important}.blue-grey.lighten-3{background-color:#b0bec5 !important}.blue-grey-text.text-lighten-3{color:#b0bec5 !important}.blue-grey.lighten-2{background-color:#90a4ae !important}.blue-grey-text.text-lighten-2{color:#90a4ae !important}.blue-grey.lighten-1{background-color:#78909c !important}.blue-grey-text.text-lighten-1{color:#78909c !important}.blue-grey.darken-1{background-color:#546e7a !important}.blue-grey-text.text-darken-1{color:#546e7a !important}.blue-grey.darken-2{background-color:#455a64 !important}.blue-grey-text.text-darken-2{color:#455a64 !important}.blue-grey.darken-3{background-color:#37474f !important}.blue-grey-text.text-darken-3{color:#37474f !important}.blue-grey.darken-4{background-color:#263238 !important}.blue-grey-text.text-darken-4{color:#263238 !important}.grey{background-color:#9e9e9e !important}.grey-text{color:#9e9e9e !important}.grey.lighten-5{background-color:#fafafa !important}.grey-text.text-lighten-5{color:#fafafa !important}.grey.lighten-4{background-color:#f5f5f5 !important}.grey-text.text-lighten-4{color:#f5f5f5 !important}.grey.lighten-3{background-color:#eee !important}.grey-text.text-lighten-3{color:#eee !important}.grey.lighten-2{background-color:#e0e0e0 !important}.grey-text.text-lighten-2{color:#e0e0e0 !important}.grey.lighten-1{background-color:#bdbdbd !important}.grey-text.text-lighten-1{color:#bdbdbd !important}.grey.darken-1{background-color:#757575 !important}.grey-text.text-darken-1{color:#757575 !important}.grey.darken-2{background-color:#616161 !important}.grey-text.text-darken-2{color:#616161 !important}.grey.darken-3{background-color:#424242 !important}.grey-text.text-darken-3{color:#424242 !important}.grey.darken-4{background-color:#212121 !important}.grey-text.text-darken-4{color:#212121 !important}.black{background-color:#000 !important}.black-text{color:#000 !important}.white{background-color:#fff !important}.white-text{color:#fff !important}.transparent{background-color:rgba(0,0,0,0) !important}.transparent-text{color:rgba(0,0,0,0) !important}/*! normalize.css v7.0.0 | MIT License | github.com/necolas/normalize.css */html{line-height:1.15;-ms-text-size-adjust:100%;-webkit-text-size-adjust:100%}body{margin:0}article,aside,footer,header,nav,section{display:block}h1{font-size:2em;margin:0.67em 0}figcaption,figure,main{display:block}figure{margin:1em 40px}hr{-webkit-box-sizing:content-box;box-sizing:content-box;height:0;overflow:visible}pre{font-family:monospace, monospace;font-size:1em}a{background-color:transparent;-webkit-text-decoration-skip:objects}abbr[title]{border-bottom:none;text-decoration:underline;-webkit-text-decoration:underline dotted;-moz-text-decoration:underline dotted;text-decoration:underline dotted}b,strong{font-weight:inherit}b,strong{font-weight:bolder}code,kbd,samp{font-family:monospace, monospace;font-size:1em}dfn{font-style:italic}mark{background-color:#ff0;color:#000}small{font-size:80%}sub,sup{font-size:75%;line-height:0;position:relative;vertical-align:baseline}sub{bottom:-0.25em}sup{top:-0.5em}audio,video{display:inline-block}audio:not([controls]){display:none;height:0}img{border-style:none}svg:not(:root){overflow:hidden}button,input,optgroup,select,textarea{font-family:sans-serif;font-size:100%;line-height:1.15;margin:0}button,input{overflow:visible}button,select{text-transform:none}button,html [type="button"],[type="reset"],[type="submit"]{-webkit-appearance:button}button::-moz-focus-inner,[type="button"]::-moz-focus-inner,[type="reset"]::-moz-focus-inner,[type="submit"]::-moz-focus-inner{border-style:none;padding:0}button:-moz-focusring,[type="button"]:-moz-focusring,[type="reset"]:-moz-focusring,[type="submit"]:-moz-focusring{outline:1px dotted ButtonText}fieldset{padding:0.35em 0.75em 0.625em}legend{-webkit-box-sizing:border-box;box-sizing:border-box;color:inherit;display:table;max-width:100%;padding:0;white-space:normal}progress{display:inline-block;vertical-align:baseline}textarea{overflow:auto}[type="checkbox"],[type="radio"]{-webkit-box-sizing:border-box;box-sizing:border-box;padding:0}[type="number"]::-webkit-inner-spin-button,[type="number"]::-webkit-outer-spin-button{height:auto}[type="search"]{-webkit-appearance:textfield;outline-offset:-2px}[type="search"]::-webkit-search-cancel-button,[type="search"]::-webkit-search-decoration{-webkit-appearance:none}::-webkit-file-upload-button{-webkit-appearance:button;font:inherit}details,menu{display:block}summary{display:list-item}canvas{display:inline-block}template{display:none}[hidden]{display:none}html{-webkit-box-sizing:border-box;box-sizing:border-box}*,*:before,*:after{-webkit-box-sizing:inherit;box-sizing:inherit}button,input,optgroup,select,textarea{font-family:-apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,Oxygen-Sans,Ubuntu,Cantarell,"Helvetica Neue",sans-serif}ul:not(.browser-default){padding-left:0;list-style-type:none}ul:not(.browser-default)>li{list-style-type:none}a{color:#039be5;text-decoration:none;-webkit-tap-highlight-color:transparent}.valign-wrapper{display:-webkit-box;display:-webkit-flex;display:-ms-flexbox;display:flex;-webkit-box-align:center;-webkit-align-items:center;-ms-flex-align:center;align-items:center}.clearfix{clear:both}.z-depth-0{-webkit-box-shadow:none !important;box-shadow:none !important}.z-depth-1,nav,.card-panel,.card,.toast,.btn,.btn-large,.btn-small,.btn-floating,.dropdown-content,.collapsible,.sidenav{-webkit-box-shadow:0 2px 2px 0 rgba(0,0,0,0.14),0 3px 1px -2px rgba(0,0,0,0.12),0 1px 5px 0 rgba(0,0,0,0.2);box-shadow:0 2px 2px 0 rgba(0,0,0,0.14),0 3px 1px -2px rgba(0,0,0,0.12),0 1px 5px 0 rgba(0,0,0,0.2)}.z-depth-1-half,.btn:hover,.btn-large:hover,.btn-small:hover,.btn-floating:hover{-webkit-box-shadow:0 3px 3px 0 rgba(0,0,0,0.14),0 1px 7px 0 rgba(0,0,0,0.12),0 3px 1px -1px rgba(0,0,0,0.2);box-shadow:0 3px 3px 0 rgba(0,0,0,0.14),0 1px 7px 0 rgba(0,0,0,0.12),0 3px 1px -1px rgba(0,0,0,0.2)}.z-depth-2{-webkit-box-shadow:0 4px 5px 0 rgba(0,0,0,0.14),0 1px 10px 0 rgba(0,0,0,0.12),0 2px 4px -1px rgba(0,0,0,0.3);box-shadow:0 4px 5px 0 rgba(0,0,0,0.14),0 1px 10px 0 rgba(0,0,0,0.12),0 2px 4px -1px rgba(0,0,0,0.3)}.z-depth-3{-webkit-box-shadow:0 8px 17px 2px rgba(0,0,0,0.14),0 3px 14px 2px rgba(0,0,0,0.12),0 5px 5px -3px rgba(0,0,0,0.2);box-shadow:0 8px 17px 2px rgba(0,0,0,0.14),0 3px 14px 2px rgba(0,0,0,0.12),0 5px 5px -3px rgba(0,0,0,0.2)}.z-depth-4{-webkit-box-shadow:0 16px 24px 2px rgba(0,0,0,0.14),0 6px 30px 5px rgba(0,0,0,0.12),0 8px 10px -7px rgba(0,0,0,0.2);box-shadow:0 16px 24px 2px rgba(0,0,0,0.14),0 6px 30px 5px rgba(0,0,0,0.12),0 8px 10px -7px rgba(0,0,0,0.2)}.z-depth-5,.modal{-webkit-box-shadow:0 24px 38px 3px rgba(0,0,0,0.14),0 9px 46px 8px rgba(0,0,0,0.12),0 11px 15px -7px rgba(0,0,0,0.2);box-shadow:0 24px 38px 3px rgba(0,0,0,0.14),0 9px 46px 8px rgba(0,0,0,0.12),0 11px 15px -7px rgba(0,0,0,0.2)}.hoverable{-webkit-transition:-webkit-box-shadow .25s;transition:-webkit-box-shadow .25s;transition:box-shadow .25s;transition:box-shadow .25s, -webkit-box-shadow .25s}.hoverable:hover{-webkit-box-shadow:0 8px 17px 0 rgba(0,0,0,0.2),0 6px 20px 0 rgba(0,0,0,0.19);box-shadow:0 8px 17px 0 rgba(0,0,0,0.2),0 6px 20px 0 rgba(0,0,0,0.19)}.divider{height:1px;overflow:hidden;background-color:#e0e0e0}blockquote{margin:20px 0;padding-left:1.5rem;border-left:5px solid #ee6e73}i{line-height:inherit}i.left{float:left;margin-right:15px}i.right{float:right;margin-left:15px}i.tiny{font-size:1rem}i.small{font-size:2rem}i.medium{font-size:4rem}i.large{font-size:6rem}img.responsive-img,video.responsive-video{max-width:100%;height:auto}.pagination li{display:inline-block;border-radius:2px;text-align:center;vertical-align:top;height:30px}.pagination li a{color:#444;display:inline-block;font-size:1.2rem;padding:0 10px;line-height:30px}.pagination li.active a{color:#fff}.pagination li.active{background-color:#ee6e73}.pagination li.disabled a{cursor:default;color:#999}.pagination li i{font-size:2rem}.pagination li.pages ul li{display:inline-block;float:none}@media only screen and (max-width: 992px){.pagination{width:100%}.pagination li.prev,.pagination li.next{width:10%}.pagination li.pages{width:80%;overflow:hidden;white-space:nowrap}}.breadcrumb{font-size:18px;color:rgba(255,255,255,0.7)}.breadcrumb i,.breadcrumb [class^="mdi-"],.breadcrumb [class*="mdi-"],.breadcrumb i.material-icons{display:inline-block;float:left;font-size:24px}.breadcrumb:before{content:'\E5CC';color:rgba(255,255,255,0.7);vertical-align:top;display:inline-block;font-family:'Material Icons';font-weight:normal;font-style:normal;font-size:25px;margin:0 10px 0 8px;-webkit-font-smoothing:antialiased}.breadcrumb:first-child:before{display:none}.breadcrumb:last-child{color:#fff}.parallax-container{position:relative;overflow:hidden;height:500px}.parallax-container .parallax{position:absolute;top:0;left:0;right:0;bottom:0;z-index:-1}.parallax-container .parallax img{opacity:0;position:absolute;left:50%;bottom:0;min-width:100%;min-height:100%;-webkit-transform:translate3d(0, 0, 0);transform:translate3d(0, 0, 0);-webkit-transform:translateX(-50%);transform:translateX(-50%)}.pin-top,.pin-bottom{position:relative}.pinned{position:fixed !important}ul.staggered-list li{opacity:0}.fade-in{opacity:0;-webkit-transform-origin:0 50%;transform-origin:0 50%}@media only screen and (max-width: 600px){.hide-on-small-only,.hide-on-small-and-down{display:none !important}}@media only screen and (max-width: 992px){.hide-on-med-and-down{display:none !important}}@media only screen and (min-width: 601px){.hide-on-med-and-up{display:none !important}}@media only screen and (min-width: 600px) and (max-width: 992px){.hide-on-med-only{display:none !important}}@media only screen and (min-width: 993px){.hide-on-large-only{display:none !important}}@media only screen and (min-width: 1201px){.hide-on-extra-large-only{display:none !important}}@media only screen and (min-width: 1201px){.show-on-extra-large{display:block !important}}@media only screen and (min-width: 993px){.show-on-large{display:block !important}}@media only screen and (min-width: 600px) and (max-width: 992px){.show-on-medium{display:block !important}}@media only screen and (max-width: 600px){.show-on-small{display:block !important}}@media only screen and (min-width: 601px){.show-on-medium-and-up{display:block !important}}@media only screen and (max-width: 992px){.show-on-medium-and-down{display:block !important}}@media only screen and (max-width: 600px){.center-on-small-only{text-align:center}}.page-footer{padding-top:20px;color:#fff;background-color:#ee6e73}.page-footer .footer-copyright{overflow:hidden;min-height:50px;display:-webkit-box;display:-webkit-flex;display:-ms-flexbox;display:flex;-webkit-box-align:center;-webkit-align-items:center;-ms-flex-align:center;align-items:center;-webkit-box-pack:justify;-webkit-justify-content:space-between;-ms-flex-pack:justify;justify-content:space-between;padding:10px 0px;color:rgba(255,255,255,0.8);background-color:rgba(51,51,51,0.08)}table,th,td{border:none}table{width:100%;display:table;border-collapse:collapse;border-spacing:0}table.striped tr{border-bottom:none}table.striped>tbody>tr:nth-child(odd){background-color:rgba(242,242,242,0.5)}table.striped>tbody>tr>td{border-radius:0}table.highlight>tbody>tr{-webkit-transition:background-color .25s ease;transition:background-color .25s ease}table.highlight>tbody>tr:hover{background-color:rgba(242,242,242,0.5)}table.centered thead tr th,table.centered tbody tr td{text-align:center}tr{border-bottom:1px solid rgba(0,0,0,0.12)}td,th{padding:15px 5px;display:table-cell;text-align:left;vertical-align:middle;border-radius:2px}@media only screen and (max-width: 992px){table.responsive-table{width:100%;border-collapse:collapse;border-spacing:0;display:block;position:relative}table.responsive-table td:empty:before{content:'\00a0'}table.responsive-table th,table.responsive-table td{margin:0;vertical-align:top}table.responsive-table th{text-align:left}table.responsive-table thead{display:block;float:left}table.responsive-table thead tr{display:block;padding:0 10px 0 0}table.responsive-table thead tr th::before{content:"\00a0"}table.responsive-table tbody{display:block;width:auto;position:relative;overflow-x:auto;white-space:nowrap}table.responsive-table tbody tr{display:inline-block;vertical-align:top}table.responsive-table th{display:block;text-align:right}table.responsive-table td{display:block;min-height:1.25em;text-align:left}table.responsive-table tr{border-bottom:none;padding:0 10px}table.responsive-table thead{border:0;border-right:1px solid rgba(0,0,0,0.12)}}.collection{margin:.5rem 0 1rem 0;border:1px solid #e0e0e0;border-radius:2px;overflow:hidden;position:relative}.collection .collection-item{background-color:#fff;line-height:1.5rem;padding:10px 20px;margin:0;border-bottom:1px solid #e0e0e0}.collection .collection-item.avatar{min-height:84px;padding-left:72px;position:relative}.collection .collection-item.avatar:not(.circle-clipper)>.circle,.collection .collection-item.avatar :not(.circle-clipper)>.circle{position:absolute;width:42px;height:42px;overflow:hidden;left:15px;display:inline-block;vertical-align:middle}.collection .collection-item.avatar i.circle{font-size:18px;line-height:42px;color:#fff;background-color:#999;text-align:center}.collection .collection-item.avatar .title{font-size:16px}.collection .collection-item.avatar p{margin:0}.collection .collection-item.avatar .secondary-content{position:absolute;top:16px;right:16px}.collection .collection-item:last-child{border-bottom:none}.collection .collection-item.active{background-color:#26a69a;color:#eafaf9}.collection .collection-item.active .secondary-content{color:#fff}.collection a.collection-item{display:block;-webkit-transition:.25s;transition:.25s;color:#26a69a}.collection a.collection-item:not(.active):hover{background-color:#ddd}.collection.with-header .collection-header{background-color:#fff;border-bottom:1px solid #e0e0e0;padding:10px 20px}.collection.with-header .collection-item{padding-left:30px}.collection.with-header .collection-item.avatar{padding-left:72px}.secondary-content{float:right;color:#26a69a}.collapsible .collection{margin:0;border:none}.video-container{position:relative;padding-bottom:56.25%;height:0;overflow:hidden}.video-container iframe,.video-container object,.video-container embed{position:absolute;top:0;left:0;width:100%;height:100%}.progress{position:relative;height:4px;display:block;width:100%;background-color:#acece6;border-radius:2px;margin:.5rem 0 1rem 0;overflow:hidden}.progress .determinate{position:absolute;top:0;left:0;bottom:0;background-color:#26a69a;-webkit-transition:width .3s linear;transition:width .3s linear}.progress .indeterminate{background-color:#26a69a}.progress .indeterminate:before{content:'';position:absolute;background-color:inherit;top:0;left:0;bottom:0;will-change:left, right;-webkit-animation:indeterminate 2.1s cubic-bezier(0.65, 0.815, 0.735, 0.395) infinite;animation:indeterminate 2.1s cubic-bezier(0.65, 0.815, 0.735, 0.395) infinite}.progress .indeterminate:after{content:'';position:absolute;background-color:inherit;top:0;left:0;bottom:0;will-change:left, right;-webkit-animation:indeterminate-short 2.1s cubic-bezier(0.165, 0.84, 0.44, 1) infinite;animation:indeterminate-short 2.1s cubic-bezier(0.165, 0.84, 0.44, 1) infinite;-webkit-animation-delay:1.15s;animation-delay:1.15s}@-webkit-keyframes indeterminate{0%{left:-35%;right:100%}60%{left:100%;right:-90%}100%{left:100%;right:-90%}}@keyframes indeterminate{0%{left:-35%;right:100%}60%{left:100%;right:-90%}100%{left:100%;right:-90%}}@-webkit-keyframes indeterminate-short{0%{left:-200%;right:100%}60%{left:107%;right:-8%}100%{left:107%;right:-8%}}@keyframes indeterminate-short{0%{left:-200%;right:100%}60%{left:107%;right:-8%}100%{left:107%;right:-8%}}.hide{display:none !important}.left-align{text-align:left}.right-align{text-align:right}.center,.center-align{text-align:center}.left{float:left !important}.right{float:right !important}.no-select,input[type=range],input[type=range]+.thumb{-webkit-user-select:none;-moz-user-select:none;-ms-user-select:none;user-select:none}.circle{border-radius:50%}.center-block{display:block;margin-left:auto;margin-right:auto}.truncate{display:block;white-space:nowrap;overflow:hidden;text-overflow:ellipsis}.no-padding{padding:0 !important}span.badge{min-width:3rem;padding:0 6px;margin-left:14px;text-align:center;font-size:1rem;line-height:22px;height:22px;color:#757575;float:right;-webkit-box-sizing:border-box;box-sizing:border-box}span.badge.new{font-weight:300;font-size:0.8rem;color:#fff;background-color:#26a69a;border-radius:2px}span.badge.new:after{content:" new"}span.badge[data-badge-caption]::after{content:" " attr(data-badge-caption)}nav ul a span.badge{display:inline-block;float:none;margin-left:4px;line-height:22px;height:22px;-webkit-font-smoothing:auto}.collection-item span.badge{margin-top:calc(.75rem - 11px)}.collapsible span.badge{margin-left:auto}.sidenav span.badge{margin-top:calc(24px - 11px)}table span.badge{display:inline-block;float:none;margin-left:auto}.material-icons{text-rendering:optimizeLegibility;-webkit-font-feature-settings:'liga';-moz-font-feature-settings:'liga';font-feature-settings:'liga'}.container{margin:0 auto;max-width:1280px;width:90%}@media only screen and (min-width: 601px){.container{width:85%}}@media only screen and (min-width: 993px){.container{width:70%}}.col .row{margin-left:-.75rem;margin-right:-.75rem}.section{padding-top:1rem;padding-bottom:1rem}.section.no-pad{padding:0}.section.no-pad-bot{padding-bottom:0}.section.no-pad-top{padding-top:0}.row{margin-left:auto;margin-right:auto;margin-bottom:20px}.row:after{content:"";display:table;clear:both}.row .col{float:left;-webkit-box-sizing:border-box;box-sizing:border-box;padding:0 .75rem;min-height:1px}.row .col[class*="push-"],.row .col[class*="pull-"]{position:relative}.row .col.s1{width:8.3333333333%;margin-left:auto;left:auto;right:auto}.row .col.s2{width:16.6666666667%;margin-left:auto;left:auto;right:auto}.row .col.s3{width:25%;margin-left:auto;left:auto;right:auto}.row .col.s4{width:33.3333333333%;margin-left:auto;left:auto;right:auto}.row .col.s5{width:41.6666666667%;margin-left:auto;left:auto;right:auto}.row .col.s6{width:50%;margin-left:auto;left:auto;right:auto}.row .col.s7{width:58.3333333333%;margin-left:auto;left:auto;right:auto}.row .col.s8{width:66.6666666667%;margin-left:auto;left:auto;right:auto}.row .col.s9{width:75%;margin-left:auto;left:auto;right:auto}.row .col.s10{width:83.3333333333%;margin-left:auto;left:auto;right:auto}.row .col.s11{width:91.6666666667%;margin-left:auto;left:auto;right:auto}.row .col.s12{width:100%;margin-left:auto;left:auto;right:auto}.row .col.offset-s1{margin-left:8.3333333333%}.row .col.pull-s1{right:8.3333333333%}.row .col.push-s1{left:8.3333333333%}.row .col.offset-s2{margin-left:16.6666666667%}.row .col.pull-s2{right:16.6666666667%}.row .col.push-s2{left:16.6666666667%}.row .col.offset-s3{margin-left:25%}.row .col.pull-s3{right:25%}.row .col.push-s3{left:25%}.row .col.offset-s4{margin-left:33.3333333333%}.row .col.pull-s4{right:33.3333333333%}.row .col.push-s4{left:33.3333333333%}.row .col.offset-s5{margin-left:41.6666666667%}.row .col.pull-s5{right:41.6666666667%}.row .col.push-s5{left:41.6666666667%}.row .col.offset-s6{margin-left:50%}.row .col.pull-s6{right:50%}.row .col.push-s6{left:50%}.row .col.offset-s7{margin-left:58.3333333333%}.row .col.pull-s7{right:58.3333333333%}.row .col.push-s7{left:58.3333333333%}.row .col.offset-s8{margin-left:66.6666666667%}.row .col.pull-s8{right:66.6666666667%}.row .col.push-s8{left:66.6666666667%}.row .col.offset-s9{margin-left:75%}.row .col.pull-s9{right:75%}.row .col.push-s9{left:75%}.row .col.offset-s10{margin-left:83.3333333333%}.row .col.pull-s10{right:83.3333333333%}.row .col.push-s10{left:83.3333333333%}.row .col.offset-s11{margin-left:91.6666666667%}.row .col.pull-s11{right:91.6666666667%}.row .col.push-s11{left:91.6666666667%}.row .col.offset-s12{margin-left:100%}.row .col.pull-s12{right:100%}.row .col.push-s12{left:100%}@media only screen and (min-width: 601px){.row .col.m1{width:8.3333333333%;margin-left:auto;left:auto;right:auto}.row .col.m2{width:16.6666666667%;margin-left:auto;left:auto;right:auto}.row .col.m3{width:25%;margin-left:auto;left:auto;right:auto}.row .col.m4{width:33.3333333333%;margin-left:auto;left:auto;right:auto}.row .col.m5{width:41.6666666667%;margin-left:auto;left:auto;right:auto}.row .col.m6{width:50%;margin-left:auto;left:auto;right:auto}.row .col.m7{width:58.3333333333%;margin-left:auto;left:auto;right:auto}.row .col.m8{width:66.6666666667%;margin-left:auto;left:auto;right:auto}.row .col.m9{width:75%;margin-left:auto;left:auto;right:auto}.row .col.m10{width:83.3333333333%;margin-left:auto;left:auto;right:auto}.row .col.m11{width:91.6666666667%;margin-left:auto;left:auto;right:auto}.row .col.m12{width:100%;margin-left:auto;left:auto;right:auto}.row .col.offset-m1{margin-left:8.3333333333%}.row .col.pull-m1{right:8.3333333333%}.row .col.push-m1{left:8.3333333333%}.row .col.offset-m2{margin-left:16.6666666667%}.row .col.pull-m2{right:16.6666666667%}.row .col.push-m2{left:16.6666666667%}.row .col.offset-m3{margin-left:25%}.row .col.pull-m3{right:25%}.row .col.push-m3{left:25%}.row .col.offset-m4{margin-left:33.3333333333%}.row .col.pull-m4{right:33.3333333333%}.row .col.push-m4{left:33.3333333333%}.row .col.offset-m5{margin-left:41.6666666667%}.row .col.pull-m5{right:41.6666666667%}.row .col.push-m5{left:41.6666666667%}.row .col.offset-m6{margin-left:50%}.row .col.pull-m6{right:50%}.row .col.push-m6{left:50%}.row .col.offset-m7{margin-left:58.3333333333%}.row .col.pull-m7{right:58.3333333333%}.row .col.push-m7{left:58.3333333333%}.row .col.offset-m8{margin-left:66.6666666667%}.row .col.pull-m8{right:66.6666666667%}.row .col.push-m8{left:66.6666666667%}.row .col.offset-m9{margin-left:75%}.row .col.pull-m9{right:75%}.row .col.push-m9{left:75%}.row .col.offset-m10{margin-left:83.3333333333%}.row .col.pull-m10{right:83.3333333333%}.row .col.push-m10{left:83.3333333333%}.row .col.offset-m11{margin-left:91.6666666667%}.row .col.pull-m11{right:91.6666666667%}.row .col.push-m11{left:91.6666666667%}.row .col.offset-m12{margin-left:100%}.row .col.pull-m12{right:100%}.row .col.push-m12{left:100%}}@media only screen and (min-width: 993px){.row .col.l1{width:8.3333333333%;margin-left:auto;left:auto;right:auto}.row .col.l2{width:16.6666666667%;margin-left:auto;left:auto;right:auto}.row .col.l3{width:25%;margin-left:auto;left:auto;right:auto}.row .col.l4{width:33.3333333333%;margin-left:auto;left:auto;right:auto}.row .col.l5{width:41.6666666667%;margin-left:auto;left:auto;right:auto}.row .col.l6{width:50%;margin-left:auto;left:auto;right:auto}.row .col.l7{width:58.3333333333%;margin-left:auto;left:auto;right:auto}.row .col.l8{width:66.6666666667%;margin-left:auto;left:auto;right:auto}.row .col.l9{width:75%;margin-left:auto;left:auto;right:auto}.row .col.l10{width:83.3333333333%;margin-left:auto;left:auto;right:auto}.row .col.l11{width:91.6666666667%;margin-left:auto;left:auto;right:auto}.row .col.l12{width:100%;margin-left:auto;left:auto;right:auto}.row .col.offset-l1{margin-left:8.3333333333%}.row .col.pull-l1{right:8.3333333333%}.row .col.push-l1{left:8.3333333333%}.row .col.offset-l2{margin-left:16.6666666667%}.row .col.pull-l2{right:16.6666666667%}.row .col.push-l2{left:16.6666666667%}.row .col.offset-l3{margin-left:25%}.row .col.pull-l3{right:25%}.row .col.push-l3{left:25%}.row .col.offset-l4{margin-left:33.3333333333%}.row .col.pull-l4{right:33.3333333333%}.row .col.push-l4{left:33.3333333333%}.row .col.offset-l5{margin-left:41.6666666667%}.row .col.pull-l5{right:41.6666666667%}.row .col.push-l5{left:41.6666666667%}.row .col.offset-l6{margin-left:50%}.row .col.pull-l6{right:50%}.row .col.push-l6{left:50%}.row .col.offset-l7{margin-left:58.3333333333%}.row .col.pull-l7{right:58.3333333333%}.row .col.push-l7{left:58.3333333333%}.row .col.offset-l8{margin-left:66.6666666667%}.row .col.pull-l8{right:66.6666666667%}.row .col.push-l8{left:66.6666666667%}.row .col.offset-l9{margin-left:75%}.row .col.pull-l9{right:75%}.row .col.push-l9{left:75%}.row .col.offset-l10{margin-left:83.3333333333%}.row .col.pull-l10{right:83.3333333333%}.row .col.push-l10{left:83.3333333333%}.row .col.offset-l11{margin-left:91.6666666667%}.row .col.pull-l11{right:91.6666666667%}.row .col.push-l11{left:91.6666666667%}.row .col.offset-l12{margin-left:100%}.row .col.pull-l12{right:100%}.row .col.push-l12{left:100%}}@media only screen and (min-width: 1201px){.row .col.xl1{width:8.3333333333%;margin-left:auto;left:auto;right:auto}.row .col.xl2{width:16.6666666667%;margin-left:auto;left:auto;right:auto}.row .col.xl3{width:25%;margin-left:auto;left:auto;right:auto}.row .col.xl4{width:33.3333333333%;margin-left:auto;left:auto;right:auto}.row .col.xl5{width:41.6666666667%;margin-left:auto;left:auto;right:auto}.row .col.xl6{width:50%;margin-left:auto;left:auto;right:auto}.row .col.xl7{width:58.3333333333%;margin-left:auto;left:auto;right:auto}.row .col.xl8{width:66.6666666667%;margin-left:auto;left:auto;right:auto}.row .col.xl9{width:75%;margin-left:auto;left:auto;right:auto}.row .col.xl10{width:83.3333333333%;margin-left:auto;left:auto;right:auto}.row .col.xl11{width:91.6666666667%;margin-left:auto;left:auto;right:auto}.row .col.xl12{width:100%;margin-left:auto;left:auto;right:auto}.row .col.offset-xl1{margin-left:8.3333333333%}.row .col.pull-xl1{right:8.3333333333%}.row .col.push-xl1{left:8.3333333333%}.row .col.offset-xl2{margin-left:16.6666666667%}.row .col.pull-xl2{right:16.6666666667%}.row .col.push-xl2{left:16.6666666667%}.row .col.offset-xl3{margin-left:25%}.row .col.pull-xl3{right:25%}.row .col.push-xl3{left:25%}.row .col.offset-xl4{margin-left:33.3333333333%}.row .col.pull-xl4{right:33.3333333333%}.row .col.push-xl4{left:33.3333333333%}.row .col.offset-xl5{margin-left:41.6666666667%}.row .col.pull-xl5{right:41.6666666667%}.row .col.push-xl5{left:41.6666666667%}.row .col.offset-xl6{margin-left:50%}.row .col.pull-xl6{right:50%}.row .col.push-xl6{left:50%}.row .col.offset-xl7{margin-left:58.3333333333%}.row .col.pull-xl7{right:58.3333333333%}.row .col.push-xl7{left:58.3333333333%}.row .col.offset-xl8{margin-left:66.6666666667%}.row .col.pull-xl8{right:66.6666666667%}.row .col.push-xl8{left:66.6666666667%}.row .col.offset-xl9{margin-left:75%}.row .col.pull-xl9{right:75%}.row .col.push-xl9{left:75%}.row .col.offset-xl10{margin-left:83.3333333333%}.row .col.pull-xl10{right:83.3333333333%}.row .col.push-xl10{left:83.3333333333%}.row .col.offset-xl11{margin-left:91.6666666667%}.row .col.pull-xl11{right:91.6666666667%}.row .col.push-xl11{left:91.6666666667%}.row .col.offset-xl12{margin-left:100%}.row .col.pull-xl12{right:100%}.row .col.push-xl12{left:100%}}nav{color:#fff;background-color:#ee6e73;width:100%;height:56px;line-height:56px}nav.nav-extended{height:auto}nav.nav-extended .nav-wrapper{min-height:56px;height:auto}nav.nav-extended .nav-content{position:relative;line-height:normal}nav a{color:#fff}nav i,nav [class^="mdi-"],nav [class*="mdi-"],nav i.material-icons{display:block;font-size:24px;height:56px;line-height:56px}nav .nav-wrapper{position:relative;height:100%}@media only screen and (min-width: 993px){nav a.sidenav-trigger{display:none}}nav .sidenav-trigger{float:left;position:relative;z-index:1;height:56px;margin:0 18px}nav .sidenav-trigger i{height:56px;line-height:56px}nav .brand-logo{position:absolute;color:#fff;display:inline-block;font-size:2.1rem;padding:0}nav .brand-logo.center{left:50%;-webkit-transform:translateX(-50%);transform:translateX(-50%)}@media only screen and (max-width: 992px){nav .brand-logo{left:50%;-webkit-transform:translateX(-50%);transform:translateX(-50%)}nav .brand-logo.left,nav .brand-logo.right{padding:0;-webkit-transform:none;transform:none}nav .brand-logo.left{left:0.5rem}nav .brand-logo.right{right:0.5rem;left:auto}}nav .brand-logo.right{right:0.5rem;padding:0}nav .brand-logo i,nav .brand-logo [class^="mdi-"],nav .brand-logo [class*="mdi-"],nav .brand-logo i.material-icons{float:left;margin-right:15px}nav .nav-title{display:inline-block;font-size:32px;padding:28px 0}nav ul{margin:0}nav ul li{-webkit-transition:background-color .3s;transition:background-color .3s;float:left;padding:0}nav ul li.active{background-color:rgba(0,0,0,0.1)}nav ul a{-webkit-transition:background-color .3s;transition:background-color .3s;font-size:1rem;color:#fff;display:block;padding:0 15px;cursor:pointer}nav ul a.btn,nav ul a.btn-large,nav ul a.btn-small,nav ul a.btn-large,nav ul a.btn-flat,nav ul a.btn-floating{margin-top:-2px;margin-left:15px;margin-right:15px}nav ul a.btn>.material-icons,nav ul a.btn-large>.material-icons,nav ul a.btn-small>.material-icons,nav ul a.btn-large>.material-icons,nav ul a.btn-flat>.material-icons,nav ul a.btn-floating>.material-icons{height:inherit;line-height:inherit}nav ul a:hover{background-color:rgba(0,0,0,0.1)}nav ul.left{float:left}nav form{height:100%}nav .input-field{margin:0;height:100%}nav .input-field input{height:100%;font-size:1.2rem;border:none;padding-left:2rem}nav .input-field input:focus,nav .input-field input[type=text]:valid,nav .input-field input[type=password]:valid,nav .input-field input[type=email]:valid,nav .input-field input[type=url]:valid,nav .input-field input[type=date]:valid{border:none;-webkit-box-shadow:none;box-shadow:none}nav .input-field label{top:0;left:0}nav .input-field label i{color:rgba(255,255,255,0.7);-webkit-transition:color .3s;transition:color .3s}nav .input-field label.active i{color:#fff}.navbar-fixed{position:relative;height:56px;z-index:997}.navbar-fixed nav{position:fixed}@media only screen and (min-width: 601px){nav.nav-extended .nav-wrapper{min-height:64px}nav,nav .nav-wrapper i,nav a.sidenav-trigger,nav a.sidenav-trigger i{height:64px;line-height:64px}.navbar-fixed{height:64px}}a{text-decoration:none}html{line-height:1.5;font-family:-apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,Oxygen-Sans,Ubuntu,Cantarell,"Helvetica Neue",sans-serif;font-weight:normal;color:rgba(0,0,0,0.87)}@media only screen and (min-width: 0){html{font-size:14px}}@media only screen and (min-width: 992px){html{font-size:14.5px}}@media only screen and (min-width: 1200px){html{font-size:15px}}h1,h2,h3,h4,h5,h6{font-weight:400;line-height:1.3}h1 a,h2 a,h3 a,h4 a,h5 a,h6 a{font-weight:inherit}h1{font-size:4.2rem;line-height:110%;margin:2.8rem 0 1.68rem 0}h2{font-size:3.56rem;line-height:110%;margin:2.3733333333rem 0 1.424rem 0}h3{font-size:2.92rem;line-height:110%;margin:1.9466666667rem 0 1.168rem 0}h4{font-size:2.28rem;line-height:110%;margin:1.52rem 0 .912rem 0}h5{font-size:1.64rem;line-height:110%;margin:1.0933333333rem 0 .656rem 0}h6{font-size:1.15rem;line-height:110%;margin:.7666666667rem 0 .46rem 0}em{font-style:italic}strong{font-weight:500}small{font-size:75%}.light{font-weight:300}.thin{font-weight:200}@media only screen and (min-width: 360px){.flow-text{font-size:1.2rem}}@media only screen and (min-width: 390px){.flow-text{font-size:1.224rem}}@media only screen and (min-width: 420px){.flow-text{font-size:1.248rem}}@media only screen and (min-width: 450px){.flow-text{font-size:1.272rem}}@media only screen and (min-width: 480px){.flow-text{font-size:1.296rem}}@media only screen and (min-width: 510px){.flow-text{font-size:1.32rem}}@media only screen and (min-width: 540px){.flow-text{font-size:1.344rem}}@media only screen and (min-width: 570px){.flow-text{font-size:1.368rem}}@media only screen and (min-width: 600px){.flow-text{font-size:1.392rem}}@media only screen and (min-width: 630px){.flow-text{font-size:1.416rem}}@media only screen and (min-width: 660px){.flow-text{font-size:1.44rem}}@media only screen and (min-width: 690px){.flow-text{font-size:1.464rem}}@media only screen and (min-width: 720px){.flow-text{font-size:1.488rem}}@media only screen and (min-width: 750px){.flow-text{font-size:1.512rem}}@media only screen and (min-width: 780px){.flow-text{font-size:1.536rem}}@media only screen and (min-width: 810px){.flow-text{font-size:1.56rem}}@media only screen and (min-width: 840px){.flow-text{font-size:1.584rem}}@media only screen and (min-width: 870px){.flow-text{font-size:1.608rem}}@media only screen and (min-width: 900px){.flow-text{font-size:1.632rem}}@media only screen and (min-width: 930px){.flow-text{font-size:1.656rem}}@media only screen and (min-width: 960px){.flow-text{font-size:1.68rem}}@media only screen and (max-width: 360px){.flow-text{font-size:1.2rem}}.scale-transition{-webkit-transition:-webkit-transform 0.3s cubic-bezier(0.53, 0.01, 0.36, 1.63) !important;transition:-webkit-transform 0.3s cubic-bezier(0.53, 0.01, 0.36, 1.63) !important;transition:transform 0.3s cubic-bezier(0.53, 0.01, 0.36, 1.63) !important;transition:transform 0.3s cubic-bezier(0.53, 0.01, 0.36, 1.63), -webkit-transform 0.3s cubic-bezier(0.53, 0.01, 0.36, 1.63) !important}.scale-transition.scale-out{-webkit-transform:scale(0);transform:scale(0);-webkit-transition:-webkit-transform .2s !important;transition:-webkit-transform .2s !important;transition:transform .2s !important;transition:transform .2s, -webkit-transform .2s !important}.scale-transition.scale-in{-webkit-transform:scale(1);transform:scale(1)}.card-panel{-webkit-transition:-webkit-box-shadow .25s;transition:-webkit-box-shadow .25s;transition:box-shadow .25s;transition:box-shadow .25s, -webkit-box-shadow .25s;padding:24px;margin:.5rem 0 1rem 0;border-radius:2px;background-color:#fff}.card{position:relative;margin:.5rem 0 1rem 0;background-color:#fff;-webkit-transition:-webkit-box-shadow .25s;transition:-webkit-box-shadow .25s;transition:box-shadow .25s;transition:box-shadow .25s, -webkit-box-shadow .25s;border-radius:2px}.card .card-title{font-size:24px;font-weight:300}.card .card-title.activator{cursor:pointer}.card.small,.card.medium,.card.large{position:relative}.card.small .card-image,.card.medium .card-image,.card.large .card-image{max-height:60%;overflow:hidden}.card.small .card-image+.card-content,.card.medium .card-image+.card-content,.card.large .card-image+.card-content{max-height:40%}.card.small .card-content,.card.medium .card-content,.card.large .card-content{max-height:100%;overflow:hidden}.card.small .card-action,.card.medium .card-action,.card.large .card-action{position:absolute;bottom:0;left:0;right:0}.card.small{height:300px}.card.medium{height:400px}.card.large{height:500px}.card.horizontal{display:-webkit-box;display:-webkit-flex;display:-ms-flexbox;display:flex}.card.horizontal.small .card-image,.card.horizontal.medium .card-image,.card.horizontal.large .card-image{height:100%;max-height:none;overflow:visible}.card.horizontal.small .card-image img,.card.horizontal.medium .card-image img,.card.horizontal.large .card-image img{height:100%}.card.horizontal .card-image{max-width:50%}.card.horizontal .card-image img{border-radius:2px 0 0 2px;max-width:100%;width:auto}.card.horizontal .card-stacked{display:-webkit-box;display:-webkit-flex;display:-ms-flexbox;display:flex;-webkit-box-orient:vertical;-webkit-box-direction:normal;-webkit-flex-direction:column;-ms-flex-direction:column;flex-direction:column;-webkit-box-flex:1;-webkit-flex:1;-ms-flex:1;flex:1;position:relative}.card.horizontal .card-stacked .card-content{-webkit-box-flex:1;-webkit-flex-grow:1;-ms-flex-positive:1;flex-grow:1}.card.sticky-action .card-action{z-index:2}.card.sticky-action .card-reveal{z-index:1;padding-bottom:64px}.card .card-image{position:relative}.card .card-image img{display:block;border-radius:2px 2px 0 0;position:relative;left:0;right:0;top:0;bottom:0;width:100%}.card .card-image .card-title{color:#fff;position:absolute;bottom:0;left:0;max-width:100%;padding:24px}.card .card-content{padding:24px;border-radius:0 0 2px 2px}.card .card-content p{margin:0}.card .card-content .card-title{display:block;line-height:32px;margin-bottom:8px}.card .card-content .card-title i{line-height:32px}.card .card-action{background-color:inherit;border-top:1px solid rgba(160,160,160,0.2);position:relative;padding:16px 24px}.card .card-action:last-child{border-radius:0 0 2px 2px}.card .card-action a:not(.btn):not(.btn-large):not(.btn-small):not(.btn-large):not(.btn-floating){color:#ffab40;margin-right:24px;-webkit-transition:color .3s ease;transition:color .3s ease;text-transform:uppercase}.card .card-action a:not(.btn):not(.btn-large):not(.btn-small):not(.btn-large):not(.btn-floating):hover{color:#ffd8a6}.card .card-reveal{padding:24px;position:absolute;background-color:#fff;width:100%;overflow-y:auto;left:0;top:100%;height:100%;z-index:3;display:none}.card .card-reveal .card-title{cursor:pointer;display:block}#toast-container{display:block;position:fixed;z-index:10000}@media only screen and (max-width: 600px){#toast-container{min-width:100%;bottom:0%}}@media only screen and (min-width: 601px) and (max-width: 992px){#toast-container{left:5%;bottom:7%;max-width:90%}}@media only screen and (min-width: 993px){#toast-container{top:10%;right:7%;max-width:86%}}.toast{border-radius:2px;top:35px;width:auto;margin-top:10px;position:relative;max-width:100%;height:auto;min-height:48px;line-height:1.5em;background-color:#323232;padding:10px 25px;font-size:1.1rem;font-weight:300;color:#fff;display:-webkit-box;display:-webkit-flex;display:-ms-flexbox;display:flex;-webkit-box-align:center;-webkit-align-items:center;-ms-flex-align:center;align-items:center;-webkit-box-pack:justify;-webkit-justify-content:space-between;-ms-flex-pack:justify;justify-content:space-between;cursor:default}.toast .toast-action{color:#eeff41;font-weight:500;margin-right:-25px;margin-left:3rem}.toast.rounded{border-radius:24px}@media only screen and (max-width: 600px){.toast{width:100%;border-radius:0}}.tabs{position:relative;overflow-x:auto;overflow-y:hidden;height:48px;width:100%;background-color:#fff;margin:0 auto;white-space:nowrap}.tabs.tabs-transparent{background-color:transparent}.tabs.tabs-transparent .tab a,.tabs.tabs-transparent .tab.disabled a,.tabs.tabs-transparent .tab.disabled a:hover{color:rgba(255,255,255,0.7)}.tabs.tabs-transparent .tab a:hover,.tabs.tabs-transparent .tab a.active{color:#fff}.tabs.tabs-transparent .indicator{background-color:#fff}.tabs.tabs-fixed-width{display:-webkit-box;display:-webkit-flex;display:-ms-flexbox;display:flex}.tabs.tabs-fixed-width .tab{-webkit-box-flex:1;-webkit-flex-grow:1;-ms-flex-positive:1;flex-grow:1}.tabs .tab{display:inline-block;text-align:center;line-height:48px;height:48px;padding:0;margin:0;text-transform:uppercase}.tabs .tab a{color:rgba(238,110,115,0.7);display:block;width:100%;height:100%;padding:0 24px;font-size:14px;text-overflow:ellipsis;overflow:hidden;-webkit-transition:color .28s ease, background-color .28s ease;transition:color .28s ease, background-color .28s ease}.tabs .tab a:focus,.tabs .tab a:focus.active{background-color:rgba(246,178,181,0.2);outline:none}.tabs .tab a:hover,.tabs .tab a.active{background-color:transparent;color:#ee6e73}.tabs .tab.disabled a,.tabs .tab.disabled a:hover{color:rgba(238,110,115,0.4);cursor:default}.tabs .indicator{position:absolute;bottom:0;height:2px;background-color:#f6b2b5;will-change:left, right}@media only screen and (max-width: 992px){.tabs{display:-webkit-box;display:-webkit-flex;display:-ms-flexbox;display:flex}.tabs .tab{-webkit-box-flex:1;-webkit-flex-grow:1;-ms-flex-positive:1;flex-grow:1}.tabs .tab a{padding:0 12px}}.material-tooltip{padding:10px 8px;font-size:1rem;z-index:2000;background-color:transparent;border-radius:2px;color:#fff;min-height:36px;line-height:120%;opacity:0;position:absolute;text-align:center;max-width:calc(100% - 4px);overflow:hidden;left:0;top:0;pointer-events:none;visibility:hidden;background-color:#323232}.backdrop{position:absolute;opacity:0;height:7px;width:14px;border-radius:0 0 50% 50%;background-color:#323232;z-index:-1;-webkit-transform-origin:50% 0%;transform-origin:50% 0%;visibility:hidden}.btn,.btn-large,.btn-small,.btn-flat{border:none;border-radius:2px;display:inline-block;height:36px;line-height:36px;padding:0 16px;text-transform:uppercase;vertical-align:middle;-webkit-tap-highlight-color:transparent}.btn.disabled,.disabled.btn-large,.disabled.btn-small,.btn-floating.disabled,.btn-large.disabled,.btn-small.disabled,.btn-flat.disabled,.btn:disabled,.btn-large:disabled,.btn-small:disabled,.btn-floating:disabled,.btn-large:disabled,.btn-small:disabled,.btn-flat:disabled,.btn[disabled],.btn-large[disabled],.btn-small[disabled],.btn-floating[disabled],.btn-large[disabled],.btn-small[disabled],.btn-flat[disabled]{pointer-events:none;background-color:#DFDFDF !important;-webkit-box-shadow:none;box-shadow:none;color:#9F9F9F !important;cursor:default}.btn.disabled:hover,.disabled.btn-large:hover,.disabled.btn-small:hover,.btn-floating.disabled:hover,.btn-large.disabled:hover,.btn-small.disabled:hover,.btn-flat.disabled:hover,.btn:disabled:hover,.btn-large:disabled:hover,.btn-small:disabled:hover,.btn-floating:disabled:hover,.btn-large:disabled:hover,.btn-small:disabled:hover,.btn-flat:disabled:hover,.btn[disabled]:hover,.btn-large[disabled]:hover,.btn-small[disabled]:hover,.btn-floating[disabled]:hover,.btn-large[disabled]:hover,.btn-small[disabled]:hover,.btn-flat[disabled]:hover{background-color:#DFDFDF !important;color:#9F9F9F !important}.btn,.btn-large,.btn-small,.btn-floating,.btn-large,.btn-small,.btn-flat{font-size:14px;outline:0}.btn i,.btn-large i,.btn-small i,.btn-floating i,.btn-large i,.btn-small i,.btn-flat i{font-size:1.3rem;line-height:inherit}.btn:focus,.btn-large:focus,.btn-small:focus,.btn-floating:focus{background-color:#1d7d74}.btn,.btn-large,.btn-small{text-decoration:none;color:#fff;background-color:#26a69a;text-align:center;letter-spacing:.5px;-webkit-transition:background-color .2s ease-out;transition:background-color .2s ease-out;cursor:pointer}.btn:hover,.btn-large:hover,.btn-small:hover{background-color:#2bbbad}.btn-floating{display:inline-block;color:#fff;position:relative;overflow:hidden;z-index:1;width:40px;height:40px;line-height:40px;padding:0;background-color:#26a69a;border-radius:50%;-webkit-transition:background-color .3s;transition:background-color .3s;cursor:pointer;vertical-align:middle}.btn-floating:hover{background-color:#26a69a}.btn-floating:before{border-radius:0}.btn-floating.btn-large{width:56px;height:56px;padding:0}.btn-floating.btn-large.halfway-fab{bottom:-28px}.btn-floating.btn-large i{line-height:56px}.btn-floating.btn-small{width:32.4px;height:32.4px}.btn-floating.btn-small.halfway-fab{bottom:-16.2px}.btn-floating.btn-small i{line-height:32.4px}.btn-floating.halfway-fab{position:absolute;right:24px;bottom:-20px}.btn-floating.halfway-fab.left{right:auto;left:24px}.btn-floating i{width:inherit;display:inline-block;text-align:center;color:#fff;font-size:1.6rem;line-height:40px}button.btn-floating{border:none}.fixed-action-btn{position:fixed;right:23px;bottom:23px;padding-top:15px;margin-bottom:0;z-index:997}.fixed-action-btn.active ul{visibility:visible}.fixed-action-btn.direction-left,.fixed-action-btn.direction-right{padding:0 0 0 15px}.fixed-action-btn.direction-left ul,.fixed-action-btn.direction-right ul{text-align:right;right:64px;top:50%;-webkit-transform:translateY(-50%);transform:translateY(-50%);height:100%;left:auto;width:500px}.fixed-action-btn.direction-left ul li,.fixed-action-btn.direction-right ul li{display:inline-block;margin:7.5px 15px 0 0}.fixed-action-btn.direction-right{padding:0 15px 0 0}.fixed-action-btn.direction-right ul{text-align:left;direction:rtl;left:64px;right:auto}.fixed-action-btn.direction-right ul li{margin:7.5px 0 0 15px}.fixed-action-btn.direction-bottom{padding:0 0 15px 0}.fixed-action-btn.direction-bottom ul{top:64px;bottom:auto;display:-webkit-box;display:-webkit-flex;display:-ms-flexbox;display:flex;-webkit-box-orient:vertical;-webkit-box-direction:reverse;-webkit-flex-direction:column-reverse;-ms-flex-direction:column-reverse;flex-direction:column-reverse}.fixed-action-btn.direction-bottom ul li{margin:15px 0 0 0}.fixed-action-btn.toolbar{padding:0;height:56px}.fixed-action-btn.toolbar.active>a i{opacity:0}.fixed-action-btn.toolbar ul{display:-webkit-box;display:-webkit-flex;display:-ms-flexbox;display:flex;top:0;bottom:0;z-index:1}.fixed-action-btn.toolbar ul li{-webkit-box-flex:1;-webkit-flex:1;-ms-flex:1;flex:1;display:inline-block;margin:0;height:100%;-webkit-transition:none;transition:none}.fixed-action-btn.toolbar ul li a{display:block;overflow:hidden;position:relative;width:100%;height:100%;background-color:transparent;-webkit-box-shadow:none;box-shadow:none;color:#fff;line-height:56px;z-index:1}.fixed-action-btn.toolbar ul li a i{line-height:inherit}.fixed-action-btn ul{left:0;right:0;text-align:center;position:absolute;bottom:64px;margin:0;visibility:hidden}.fixed-action-btn ul li{margin-bottom:15px}.fixed-action-btn ul a.btn-floating{opacity:0}.fixed-action-btn .fab-backdrop{position:absolute;top:0;left:0;z-index:-1;width:40px;height:40px;background-color:#26a69a;border-radius:50%;-webkit-transform:scale(0);transform:scale(0)}.btn-flat{-webkit-box-shadow:none;box-shadow:none;background-color:transparent;color:#343434;cursor:pointer;-webkit-transition:background-color .2s;transition:background-color .2s}.btn-flat:focus,.btn-flat:hover{-webkit-box-shadow:none;box-shadow:none}.btn-flat:focus{background-color:rgba(0,0,0,0.1)}.btn-flat.disabled,.btn-flat.btn-flat[disabled]{background-color:transparent !important;color:#b3b2b2 !important;cursor:default}.btn-large{height:54px;line-height:54px;font-size:15px;padding:0 28px}.btn-large i{font-size:1.6rem}.btn-small{height:32.4px;line-height:32.4px;font-size:13px}.btn-small i{font-size:1.2rem}.btn-block{display:block}.dropdown-content{background-color:#fff;margin:0;display:none;min-width:100px;overflow-y:auto;opacity:0;position:absolute;left:0;top:0;z-index:9999;-webkit-transform-origin:0 0;transform-origin:0 0}.dropdown-content:focus{outline:0}.dropdown-content li{clear:both;color:rgba(0,0,0,0.87);cursor:pointer;min-height:50px;line-height:1.5rem;width:100%;text-align:left}.dropdown-content li:hover,.dropdown-content li.active{background-color:#eee}.dropdown-content li:focus{outline:none}.dropdown-content li.divider{min-height:0;height:1px}.dropdown-content li>a,.dropdown-content li>span{font-size:16px;color:#26a69a;display:block;line-height:22px;padding:14px 16px}.dropdown-content li>span>label{top:1px;left:0;height:18px}.dropdown-content li>a>i{height:inherit;line-height:inherit;float:left;margin:0 24px 0 0;width:24px}body.keyboard-focused .dropdown-content li:focus{background-color:#dadada}.input-field.col .dropdown-content [type="checkbox"]+label{top:1px;left:0;height:18px;-webkit-transform:none;transform:none}.dropdown-trigger{cursor:pointer}/*! + * Waves v0.6.0 + * http://fian.my.id/Waves + * + * Copyright 2014 Alfiana E. Sibuea and other contributors + * Released under the MIT license + * https://github.com/fians/Waves/blob/master/LICENSE + */.waves-effect{position:relative;cursor:pointer;display:inline-block;overflow:hidden;-webkit-user-select:none;-moz-user-select:none;-ms-user-select:none;user-select:none;-webkit-tap-highlight-color:transparent;vertical-align:middle;z-index:1;-webkit-transition:.3s ease-out;transition:.3s ease-out}.waves-effect .waves-ripple{position:absolute;border-radius:50%;width:20px;height:20px;margin-top:-10px;margin-left:-10px;opacity:0;background:rgba(0,0,0,0.2);-webkit-transition:all 0.7s ease-out;transition:all 0.7s ease-out;-webkit-transition-property:opacity, -webkit-transform;transition-property:opacity, -webkit-transform;transition-property:transform, opacity;transition-property:transform, opacity, -webkit-transform;-webkit-transform:scale(0);transform:scale(0);pointer-events:none}.waves-effect.waves-light .waves-ripple{background-color:rgba(255,255,255,0.45)}.waves-effect.waves-red .waves-ripple{background-color:rgba(244,67,54,0.7)}.waves-effect.waves-yellow .waves-ripple{background-color:rgba(255,235,59,0.7)}.waves-effect.waves-orange .waves-ripple{background-color:rgba(255,152,0,0.7)}.waves-effect.waves-purple .waves-ripple{background-color:rgba(156,39,176,0.7)}.waves-effect.waves-green .waves-ripple{background-color:rgba(76,175,80,0.7)}.waves-effect.waves-teal .waves-ripple{background-color:rgba(0,150,136,0.7)}.waves-effect input[type="button"],.waves-effect input[type="reset"],.waves-effect input[type="submit"]{border:0;font-style:normal;font-size:inherit;text-transform:inherit;background:none}.waves-effect img{position:relative;z-index:-1}.waves-notransition{-webkit-transition:none !important;transition:none !important}.waves-circle{-webkit-transform:translateZ(0);transform:translateZ(0);-webkit-mask-image:-webkit-radial-gradient(circle, white 100%, black 100%)}.waves-input-wrapper{border-radius:0.2em;vertical-align:bottom}.waves-input-wrapper .waves-button-input{position:relative;top:0;left:0;z-index:1}.waves-circle{text-align:center;width:2.5em;height:2.5em;line-height:2.5em;border-radius:50%;-webkit-mask-image:none}.waves-block{display:block}.waves-effect .waves-ripple{z-index:-1}.modal{display:none;position:fixed;left:0;right:0;background-color:#fafafa;padding:0;max-height:70%;width:55%;margin:auto;overflow-y:auto;border-radius:2px;will-change:top, opacity}.modal:focus{outline:none}@media only screen and (max-width: 992px){.modal{width:80%}}.modal h1,.modal h2,.modal h3,.modal h4{margin-top:0}.modal .modal-content{padding:24px}.modal .modal-close{cursor:pointer}.modal .modal-footer{border-radius:0 0 2px 2px;background-color:#fafafa;padding:4px 6px;height:56px;width:100%;text-align:right}.modal .modal-footer .btn,.modal .modal-footer .btn-large,.modal .modal-footer .btn-small,.modal .modal-footer .btn-flat{margin:6px 0}.modal-overlay{position:fixed;z-index:999;top:-25%;left:0;bottom:0;right:0;height:125%;width:100%;background:#000;display:none;will-change:opacity}.modal.modal-fixed-footer{padding:0;height:70%}.modal.modal-fixed-footer .modal-content{position:absolute;height:calc(100% - 56px);max-height:100%;width:100%;overflow-y:auto}.modal.modal-fixed-footer .modal-footer{border-top:1px solid rgba(0,0,0,0.1);position:absolute;bottom:0}.modal.bottom-sheet{top:auto;bottom:-100%;margin:0;width:100%;max-height:45%;border-radius:0;will-change:bottom, opacity}.collapsible{border-top:1px solid #ddd;border-right:1px solid #ddd;border-left:1px solid #ddd;margin:.5rem 0 1rem 0}.collapsible-header{display:-webkit-box;display:-webkit-flex;display:-ms-flexbox;display:flex;cursor:pointer;-webkit-tap-highlight-color:transparent;line-height:1.5;padding:1rem;background-color:#fff;border-bottom:1px solid #ddd}.collapsible-header:focus{outline:0}.collapsible-header i{width:2rem;font-size:1.6rem;display:inline-block;text-align:center;margin-right:1rem}.keyboard-focused .collapsible-header:focus{background-color:#eee}.collapsible-body{display:none;border-bottom:1px solid #ddd;-webkit-box-sizing:border-box;box-sizing:border-box;padding:2rem}.sidenav .collapsible,.sidenav.fixed .collapsible{border:none;-webkit-box-shadow:none;box-shadow:none}.sidenav .collapsible li,.sidenav.fixed .collapsible li{padding:0}.sidenav .collapsible-header,.sidenav.fixed .collapsible-header{background-color:transparent;border:none;line-height:inherit;height:inherit;padding:0 16px}.sidenav .collapsible-header:hover,.sidenav.fixed .collapsible-header:hover{background-color:rgba(0,0,0,0.05)}.sidenav .collapsible-header i,.sidenav.fixed .collapsible-header i{line-height:inherit}.sidenav .collapsible-body,.sidenav.fixed .collapsible-body{border:0;background-color:#fff}.sidenav .collapsible-body li a,.sidenav.fixed .collapsible-body li a{padding:0 23.5px 0 31px}.collapsible.popout{border:none;-webkit-box-shadow:none;box-shadow:none}.collapsible.popout>li{-webkit-box-shadow:0 2px 5px 0 rgba(0,0,0,0.16),0 2px 10px 0 rgba(0,0,0,0.12);box-shadow:0 2px 5px 0 rgba(0,0,0,0.16),0 2px 10px 0 rgba(0,0,0,0.12);margin:0 24px;-webkit-transition:margin 0.35s cubic-bezier(0.25, 0.46, 0.45, 0.94);transition:margin 0.35s cubic-bezier(0.25, 0.46, 0.45, 0.94)}.collapsible.popout>li.active{-webkit-box-shadow:0 5px 11px 0 rgba(0,0,0,0.18),0 4px 15px 0 rgba(0,0,0,0.15);box-shadow:0 5px 11px 0 rgba(0,0,0,0.18),0 4px 15px 0 rgba(0,0,0,0.15);margin:16px 0}.chip{display:inline-block;height:32px;font-size:13px;font-weight:500;color:rgba(0,0,0,0.6);line-height:32px;padding:0 12px;border-radius:16px;background-color:#e4e4e4;margin-bottom:5px;margin-right:5px}.chip:focus{outline:none;background-color:#26a69a;color:#fff}.chip>img{float:left;margin:0 8px 0 -12px;height:32px;width:32px;border-radius:50%}.chip .close{cursor:pointer;float:right;font-size:16px;line-height:32px;padding-left:8px}.chips{border:none;border-bottom:1px solid #9e9e9e;-webkit-box-shadow:none;box-shadow:none;margin:0 0 8px 0;min-height:45px;outline:none;-webkit-transition:all .3s;transition:all .3s}.chips.focus{border-bottom:1px solid #26a69a;-webkit-box-shadow:0 1px 0 0 #26a69a;box-shadow:0 1px 0 0 #26a69a}.chips:hover{cursor:text}.chips .input{background:none;border:0;color:rgba(0,0,0,0.6);display:inline-block;font-size:16px;height:3rem;line-height:32px;outline:0;margin:0;padding:0 !important;width:120px !important}.chips .input:focus{border:0 !important;-webkit-box-shadow:none !important;box-shadow:none !important}.chips .autocomplete-content{margin-top:0;margin-bottom:0}.prefix ~ .chips{margin-left:3rem;width:92%;width:calc(100% - 3rem)}.chips:empty ~ label{font-size:0.8rem;-webkit-transform:translateY(-140%);transform:translateY(-140%)}.materialboxed{display:block;cursor:-webkit-zoom-in;cursor:zoom-in;position:relative;-webkit-transition:opacity .4s;transition:opacity .4s;-webkit-backface-visibility:hidden}.materialboxed:hover:not(.active){opacity:.8}.materialboxed.active{cursor:-webkit-zoom-out;cursor:zoom-out}#materialbox-overlay{position:fixed;top:0;right:0;bottom:0;left:0;background-color:#292929;z-index:1000;will-change:opacity}.materialbox-caption{position:fixed;display:none;color:#fff;line-height:50px;bottom:0;left:0;width:100%;text-align:center;padding:0% 15%;height:50px;z-index:1000;-webkit-font-smoothing:antialiased}select:focus{outline:1px solid #c9f3ef}button:focus{outline:none;background-color:#2ab7a9}label{font-size:.8rem;color:#9e9e9e}::-webkit-input-placeholder{color:#d1d1d1}::-moz-placeholder{color:#d1d1d1}:-ms-input-placeholder{color:#d1d1d1}::-ms-input-placeholder{color:#d1d1d1}::placeholder{color:#d1d1d1}input:not([type]),input[type=text]:not(.browser-default),input[type=password]:not(.browser-default),input[type=email]:not(.browser-default),input[type=url]:not(.browser-default),input[type=time]:not(.browser-default),input[type=date]:not(.browser-default),input[type=datetime]:not(.browser-default),input[type=datetime-local]:not(.browser-default),input[type=tel]:not(.browser-default),input[type=number]:not(.browser-default),input[type=search]:not(.browser-default),textarea.materialize-textarea{background-color:transparent;border:none;border-bottom:1px solid #9e9e9e;border-radius:0;outline:none;height:3rem;width:100%;font-size:16px;margin:0 0 8px 0;padding:0;-webkit-box-shadow:none;box-shadow:none;-webkit-box-sizing:content-box;box-sizing:content-box;-webkit-transition:border .3s, -webkit-box-shadow .3s;transition:border .3s, -webkit-box-shadow .3s;transition:box-shadow .3s, border .3s;transition:box-shadow .3s, border .3s, -webkit-box-shadow .3s}input:not([type]):disabled,input:not([type])[readonly="readonly"],input[type=text]:not(.browser-default):disabled,input[type=text]:not(.browser-default)[readonly="readonly"],input[type=password]:not(.browser-default):disabled,input[type=password]:not(.browser-default)[readonly="readonly"],input[type=email]:not(.browser-default):disabled,input[type=email]:not(.browser-default)[readonly="readonly"],input[type=url]:not(.browser-default):disabled,input[type=url]:not(.browser-default)[readonly="readonly"],input[type=time]:not(.browser-default):disabled,input[type=time]:not(.browser-default)[readonly="readonly"],input[type=date]:not(.browser-default):disabled,input[type=date]:not(.browser-default)[readonly="readonly"],input[type=datetime]:not(.browser-default):disabled,input[type=datetime]:not(.browser-default)[readonly="readonly"],input[type=datetime-local]:not(.browser-default):disabled,input[type=datetime-local]:not(.browser-default)[readonly="readonly"],input[type=tel]:not(.browser-default):disabled,input[type=tel]:not(.browser-default)[readonly="readonly"],input[type=number]:not(.browser-default):disabled,input[type=number]:not(.browser-default)[readonly="readonly"],input[type=search]:not(.browser-default):disabled,input[type=search]:not(.browser-default)[readonly="readonly"],textarea.materialize-textarea:disabled,textarea.materialize-textarea[readonly="readonly"]{color:rgba(0,0,0,0.42);border-bottom:1px dotted rgba(0,0,0,0.42)}input:not([type]):disabled+label,input:not([type])[readonly="readonly"]+label,input[type=text]:not(.browser-default):disabled+label,input[type=text]:not(.browser-default)[readonly="readonly"]+label,input[type=password]:not(.browser-default):disabled+label,input[type=password]:not(.browser-default)[readonly="readonly"]+label,input[type=email]:not(.browser-default):disabled+label,input[type=email]:not(.browser-default)[readonly="readonly"]+label,input[type=url]:not(.browser-default):disabled+label,input[type=url]:not(.browser-default)[readonly="readonly"]+label,input[type=time]:not(.browser-default):disabled+label,input[type=time]:not(.browser-default)[readonly="readonly"]+label,input[type=date]:not(.browser-default):disabled+label,input[type=date]:not(.browser-default)[readonly="readonly"]+label,input[type=datetime]:not(.browser-default):disabled+label,input[type=datetime]:not(.browser-default)[readonly="readonly"]+label,input[type=datetime-local]:not(.browser-default):disabled+label,input[type=datetime-local]:not(.browser-default)[readonly="readonly"]+label,input[type=tel]:not(.browser-default):disabled+label,input[type=tel]:not(.browser-default)[readonly="readonly"]+label,input[type=number]:not(.browser-default):disabled+label,input[type=number]:not(.browser-default)[readonly="readonly"]+label,input[type=search]:not(.browser-default):disabled+label,input[type=search]:not(.browser-default)[readonly="readonly"]+label,textarea.materialize-textarea:disabled+label,textarea.materialize-textarea[readonly="readonly"]+label{color:rgba(0,0,0,0.42)}input:not([type]):focus:not([readonly]),input[type=text]:not(.browser-default):focus:not([readonly]),input[type=password]:not(.browser-default):focus:not([readonly]),input[type=email]:not(.browser-default):focus:not([readonly]),input[type=url]:not(.browser-default):focus:not([readonly]),input[type=time]:not(.browser-default):focus:not([readonly]),input[type=date]:not(.browser-default):focus:not([readonly]),input[type=datetime]:not(.browser-default):focus:not([readonly]),input[type=datetime-local]:not(.browser-default):focus:not([readonly]),input[type=tel]:not(.browser-default):focus:not([readonly]),input[type=number]:not(.browser-default):focus:not([readonly]),input[type=search]:not(.browser-default):focus:not([readonly]),textarea.materialize-textarea:focus:not([readonly]){border-bottom:1px solid #26a69a;-webkit-box-shadow:0 1px 0 0 #26a69a;box-shadow:0 1px 0 0 #26a69a}input:not([type]):focus:not([readonly])+label,input[type=text]:not(.browser-default):focus:not([readonly])+label,input[type=password]:not(.browser-default):focus:not([readonly])+label,input[type=email]:not(.browser-default):focus:not([readonly])+label,input[type=url]:not(.browser-default):focus:not([readonly])+label,input[type=time]:not(.browser-default):focus:not([readonly])+label,input[type=date]:not(.browser-default):focus:not([readonly])+label,input[type=datetime]:not(.browser-default):focus:not([readonly])+label,input[type=datetime-local]:not(.browser-default):focus:not([readonly])+label,input[type=tel]:not(.browser-default):focus:not([readonly])+label,input[type=number]:not(.browser-default):focus:not([readonly])+label,input[type=search]:not(.browser-default):focus:not([readonly])+label,textarea.materialize-textarea:focus:not([readonly])+label{color:#26a69a}input:not([type]):focus.valid ~ label,input[type=text]:not(.browser-default):focus.valid ~ label,input[type=password]:not(.browser-default):focus.valid ~ label,input[type=email]:not(.browser-default):focus.valid ~ label,input[type=url]:not(.browser-default):focus.valid ~ label,input[type=time]:not(.browser-default):focus.valid ~ label,input[type=date]:not(.browser-default):focus.valid ~ label,input[type=datetime]:not(.browser-default):focus.valid ~ label,input[type=datetime-local]:not(.browser-default):focus.valid ~ label,input[type=tel]:not(.browser-default):focus.valid ~ label,input[type=number]:not(.browser-default):focus.valid ~ label,input[type=search]:not(.browser-default):focus.valid ~ label,textarea.materialize-textarea:focus.valid ~ label{color:#4CAF50}input:not([type]):focus.invalid ~ label,input[type=text]:not(.browser-default):focus.invalid ~ label,input[type=password]:not(.browser-default):focus.invalid ~ label,input[type=email]:not(.browser-default):focus.invalid ~ label,input[type=url]:not(.browser-default):focus.invalid ~ label,input[type=time]:not(.browser-default):focus.invalid ~ label,input[type=date]:not(.browser-default):focus.invalid ~ label,input[type=datetime]:not(.browser-default):focus.invalid ~ label,input[type=datetime-local]:not(.browser-default):focus.invalid ~ label,input[type=tel]:not(.browser-default):focus.invalid ~ label,input[type=number]:not(.browser-default):focus.invalid ~ label,input[type=search]:not(.browser-default):focus.invalid ~ label,textarea.materialize-textarea:focus.invalid ~ label{color:#F44336}input:not([type]).validate+label,input[type=text]:not(.browser-default).validate+label,input[type=password]:not(.browser-default).validate+label,input[type=email]:not(.browser-default).validate+label,input[type=url]:not(.browser-default).validate+label,input[type=time]:not(.browser-default).validate+label,input[type=date]:not(.browser-default).validate+label,input[type=datetime]:not(.browser-default).validate+label,input[type=datetime-local]:not(.browser-default).validate+label,input[type=tel]:not(.browser-default).validate+label,input[type=number]:not(.browser-default).validate+label,input[type=search]:not(.browser-default).validate+label,textarea.materialize-textarea.validate+label{width:100%}input.valid:not([type]),input.valid:not([type]):focus,input.valid[type=text]:not(.browser-default),input.valid[type=text]:not(.browser-default):focus,input.valid[type=password]:not(.browser-default),input.valid[type=password]:not(.browser-default):focus,input.valid[type=email]:not(.browser-default),input.valid[type=email]:not(.browser-default):focus,input.valid[type=url]:not(.browser-default),input.valid[type=url]:not(.browser-default):focus,input.valid[type=time]:not(.browser-default),input.valid[type=time]:not(.browser-default):focus,input.valid[type=date]:not(.browser-default),input.valid[type=date]:not(.browser-default):focus,input.valid[type=datetime]:not(.browser-default),input.valid[type=datetime]:not(.browser-default):focus,input.valid[type=datetime-local]:not(.browser-default),input.valid[type=datetime-local]:not(.browser-default):focus,input.valid[type=tel]:not(.browser-default),input.valid[type=tel]:not(.browser-default):focus,input.valid[type=number]:not(.browser-default),input.valid[type=number]:not(.browser-default):focus,input.valid[type=search]:not(.browser-default),input.valid[type=search]:not(.browser-default):focus,textarea.materialize-textarea.valid,textarea.materialize-textarea.valid:focus,.select-wrapper.valid>input.select-dropdown{border-bottom:1px solid #4CAF50;-webkit-box-shadow:0 1px 0 0 #4CAF50;box-shadow:0 1px 0 0 #4CAF50}input.invalid:not([type]),input.invalid:not([type]):focus,input.invalid[type=text]:not(.browser-default),input.invalid[type=text]:not(.browser-default):focus,input.invalid[type=password]:not(.browser-default),input.invalid[type=password]:not(.browser-default):focus,input.invalid[type=email]:not(.browser-default),input.invalid[type=email]:not(.browser-default):focus,input.invalid[type=url]:not(.browser-default),input.invalid[type=url]:not(.browser-default):focus,input.invalid[type=time]:not(.browser-default),input.invalid[type=time]:not(.browser-default):focus,input.invalid[type=date]:not(.browser-default),input.invalid[type=date]:not(.browser-default):focus,input.invalid[type=datetime]:not(.browser-default),input.invalid[type=datetime]:not(.browser-default):focus,input.invalid[type=datetime-local]:not(.browser-default),input.invalid[type=datetime-local]:not(.browser-default):focus,input.invalid[type=tel]:not(.browser-default),input.invalid[type=tel]:not(.browser-default):focus,input.invalid[type=number]:not(.browser-default),input.invalid[type=number]:not(.browser-default):focus,input.invalid[type=search]:not(.browser-default),input.invalid[type=search]:not(.browser-default):focus,textarea.materialize-textarea.invalid,textarea.materialize-textarea.invalid:focus,.select-wrapper.invalid>input.select-dropdown,.select-wrapper.invalid>input.select-dropdown:focus{border-bottom:1px solid #F44336;-webkit-box-shadow:0 1px 0 0 #F44336;box-shadow:0 1px 0 0 #F44336}input:not([type]).valid ~ .helper-text[data-success],input:not([type]):focus.valid ~ .helper-text[data-success],input:not([type]).invalid ~ .helper-text[data-error],input:not([type]):focus.invalid ~ .helper-text[data-error],input[type=text]:not(.browser-default).valid ~ .helper-text[data-success],input[type=text]:not(.browser-default):focus.valid ~ .helper-text[data-success],input[type=text]:not(.browser-default).invalid ~ .helper-text[data-error],input[type=text]:not(.browser-default):focus.invalid ~ .helper-text[data-error],input[type=password]:not(.browser-default).valid ~ .helper-text[data-success],input[type=password]:not(.browser-default):focus.valid ~ .helper-text[data-success],input[type=password]:not(.browser-default).invalid ~ .helper-text[data-error],input[type=password]:not(.browser-default):focus.invalid ~ .helper-text[data-error],input[type=email]:not(.browser-default).valid ~ .helper-text[data-success],input[type=email]:not(.browser-default):focus.valid ~ .helper-text[data-success],input[type=email]:not(.browser-default).invalid ~ .helper-text[data-error],input[type=email]:not(.browser-default):focus.invalid ~ .helper-text[data-error],input[type=url]:not(.browser-default).valid ~ .helper-text[data-success],input[type=url]:not(.browser-default):focus.valid ~ .helper-text[data-success],input[type=url]:not(.browser-default).invalid ~ .helper-text[data-error],input[type=url]:not(.browser-default):focus.invalid ~ .helper-text[data-error],input[type=time]:not(.browser-default).valid ~ .helper-text[data-success],input[type=time]:not(.browser-default):focus.valid ~ .helper-text[data-success],input[type=time]:not(.browser-default).invalid ~ .helper-text[data-error],input[type=time]:not(.browser-default):focus.invalid ~ .helper-text[data-error],input[type=date]:not(.browser-default).valid ~ .helper-text[data-success],input[type=date]:not(.browser-default):focus.valid ~ .helper-text[data-success],input[type=date]:not(.browser-default).invalid ~ .helper-text[data-error],input[type=date]:not(.browser-default):focus.invalid ~ .helper-text[data-error],input[type=datetime]:not(.browser-default).valid ~ .helper-text[data-success],input[type=datetime]:not(.browser-default):focus.valid ~ .helper-text[data-success],input[type=datetime]:not(.browser-default).invalid ~ .helper-text[data-error],input[type=datetime]:not(.browser-default):focus.invalid ~ .helper-text[data-error],input[type=datetime-local]:not(.browser-default).valid ~ .helper-text[data-success],input[type=datetime-local]:not(.browser-default):focus.valid ~ .helper-text[data-success],input[type=datetime-local]:not(.browser-default).invalid ~ .helper-text[data-error],input[type=datetime-local]:not(.browser-default):focus.invalid ~ .helper-text[data-error],input[type=tel]:not(.browser-default).valid ~ .helper-text[data-success],input[type=tel]:not(.browser-default):focus.valid ~ .helper-text[data-success],input[type=tel]:not(.browser-default).invalid ~ .helper-text[data-error],input[type=tel]:not(.browser-default):focus.invalid ~ .helper-text[data-error],input[type=number]:not(.browser-default).valid ~ .helper-text[data-success],input[type=number]:not(.browser-default):focus.valid ~ .helper-text[data-success],input[type=number]:not(.browser-default).invalid ~ .helper-text[data-error],input[type=number]:not(.browser-default):focus.invalid ~ .helper-text[data-error],input[type=search]:not(.browser-default).valid ~ .helper-text[data-success],input[type=search]:not(.browser-default):focus.valid ~ .helper-text[data-success],input[type=search]:not(.browser-default).invalid ~ .helper-text[data-error],input[type=search]:not(.browser-default):focus.invalid ~ .helper-text[data-error],textarea.materialize-textarea.valid ~ .helper-text[data-success],textarea.materialize-textarea:focus.valid ~ .helper-text[data-success],textarea.materialize-textarea.invalid ~ .helper-text[data-error],textarea.materialize-textarea:focus.invalid ~ .helper-text[data-error],.select-wrapper.valid .helper-text[data-success],.select-wrapper.invalid ~ .helper-text[data-error]{color:transparent;-webkit-user-select:none;-moz-user-select:none;-ms-user-select:none;user-select:none;pointer-events:none}input:not([type]).valid ~ .helper-text:after,input:not([type]):focus.valid ~ .helper-text:after,input[type=text]:not(.browser-default).valid ~ .helper-text:after,input[type=text]:not(.browser-default):focus.valid ~ .helper-text:after,input[type=password]:not(.browser-default).valid ~ .helper-text:after,input[type=password]:not(.browser-default):focus.valid ~ .helper-text:after,input[type=email]:not(.browser-default).valid ~ .helper-text:after,input[type=email]:not(.browser-default):focus.valid ~ .helper-text:after,input[type=url]:not(.browser-default).valid ~ .helper-text:after,input[type=url]:not(.browser-default):focus.valid ~ .helper-text:after,input[type=time]:not(.browser-default).valid ~ .helper-text:after,input[type=time]:not(.browser-default):focus.valid ~ .helper-text:after,input[type=date]:not(.browser-default).valid ~ .helper-text:after,input[type=date]:not(.browser-default):focus.valid ~ .helper-text:after,input[type=datetime]:not(.browser-default).valid ~ .helper-text:after,input[type=datetime]:not(.browser-default):focus.valid ~ .helper-text:after,input[type=datetime-local]:not(.browser-default).valid ~ .helper-text:after,input[type=datetime-local]:not(.browser-default):focus.valid ~ .helper-text:after,input[type=tel]:not(.browser-default).valid ~ .helper-text:after,input[type=tel]:not(.browser-default):focus.valid ~ .helper-text:after,input[type=number]:not(.browser-default).valid ~ .helper-text:after,input[type=number]:not(.browser-default):focus.valid ~ .helper-text:after,input[type=search]:not(.browser-default).valid ~ .helper-text:after,input[type=search]:not(.browser-default):focus.valid ~ .helper-text:after,textarea.materialize-textarea.valid ~ .helper-text:after,textarea.materialize-textarea:focus.valid ~ .helper-text:after,.select-wrapper.valid ~ .helper-text:after{content:attr(data-success);color:#4CAF50}input:not([type]).invalid ~ .helper-text:after,input:not([type]):focus.invalid ~ .helper-text:after,input[type=text]:not(.browser-default).invalid ~ .helper-text:after,input[type=text]:not(.browser-default):focus.invalid ~ .helper-text:after,input[type=password]:not(.browser-default).invalid ~ .helper-text:after,input[type=password]:not(.browser-default):focus.invalid ~ .helper-text:after,input[type=email]:not(.browser-default).invalid ~ .helper-text:after,input[type=email]:not(.browser-default):focus.invalid ~ .helper-text:after,input[type=url]:not(.browser-default).invalid ~ .helper-text:after,input[type=url]:not(.browser-default):focus.invalid ~ .helper-text:after,input[type=time]:not(.browser-default).invalid ~ .helper-text:after,input[type=time]:not(.browser-default):focus.invalid ~ .helper-text:after,input[type=date]:not(.browser-default).invalid ~ .helper-text:after,input[type=date]:not(.browser-default):focus.invalid ~ .helper-text:after,input[type=datetime]:not(.browser-default).invalid ~ .helper-text:after,input[type=datetime]:not(.browser-default):focus.invalid ~ .helper-text:after,input[type=datetime-local]:not(.browser-default).invalid ~ .helper-text:after,input[type=datetime-local]:not(.browser-default):focus.invalid ~ .helper-text:after,input[type=tel]:not(.browser-default).invalid ~ .helper-text:after,input[type=tel]:not(.browser-default):focus.invalid ~ .helper-text:after,input[type=number]:not(.browser-default).invalid ~ .helper-text:after,input[type=number]:not(.browser-default):focus.invalid ~ .helper-text:after,input[type=search]:not(.browser-default).invalid ~ .helper-text:after,input[type=search]:not(.browser-default):focus.invalid ~ .helper-text:after,textarea.materialize-textarea.invalid ~ .helper-text:after,textarea.materialize-textarea:focus.invalid ~ .helper-text:after,.select-wrapper.invalid ~ .helper-text:after{content:attr(data-error);color:#F44336}input:not([type])+label:after,input[type=text]:not(.browser-default)+label:after,input[type=password]:not(.browser-default)+label:after,input[type=email]:not(.browser-default)+label:after,input[type=url]:not(.browser-default)+label:after,input[type=time]:not(.browser-default)+label:after,input[type=date]:not(.browser-default)+label:after,input[type=datetime]:not(.browser-default)+label:after,input[type=datetime-local]:not(.browser-default)+label:after,input[type=tel]:not(.browser-default)+label:after,input[type=number]:not(.browser-default)+label:after,input[type=search]:not(.browser-default)+label:after,textarea.materialize-textarea+label:after,.select-wrapper+label:after{display:block;content:"";position:absolute;top:100%;left:0;opacity:0;-webkit-transition:.2s opacity ease-out, .2s color ease-out;transition:.2s opacity ease-out, .2s color ease-out}.input-field{position:relative;margin-top:1rem;margin-bottom:1rem}.input-field.inline{display:inline-block;vertical-align:middle;margin-left:5px}.input-field.inline input,.input-field.inline .select-dropdown{margin-bottom:1rem}.input-field.col label{left:.75rem}.input-field.col .prefix ~ label,.input-field.col .prefix ~ .validate ~ label{width:calc(100% - 3rem - 1.5rem)}.input-field>label{color:#9e9e9e;position:absolute;top:0;left:0;font-size:1rem;cursor:text;-webkit-transition:color .2s ease-out, -webkit-transform .2s ease-out;transition:color .2s ease-out, -webkit-transform .2s ease-out;transition:transform .2s ease-out, color .2s ease-out;transition:transform .2s ease-out, color .2s ease-out, -webkit-transform .2s ease-out;-webkit-transform-origin:0% 100%;transform-origin:0% 100%;text-align:initial;-webkit-transform:translateY(12px);transform:translateY(12px)}.input-field>label:not(.label-icon).active{-webkit-transform:translateY(-14px) scale(0.8);transform:translateY(-14px) scale(0.8);-webkit-transform-origin:0 0;transform-origin:0 0}.input-field>input[type]:-webkit-autofill:not(.browser-default):not([type="search"])+label,.input-field>input[type=date]:not(.browser-default)+label,.input-field>input[type=time]:not(.browser-default)+label{-webkit-transform:translateY(-14px) scale(0.8);transform:translateY(-14px) scale(0.8);-webkit-transform-origin:0 0;transform-origin:0 0}.input-field .helper-text{position:relative;min-height:18px;display:block;font-size:12px;color:rgba(0,0,0,0.54)}.input-field .helper-text::after{opacity:1;position:absolute;top:0;left:0}.input-field .prefix{position:absolute;width:3rem;font-size:2rem;-webkit-transition:color .2s;transition:color .2s;top:.5rem}.input-field .prefix.active{color:#26a69a}.input-field .prefix ~ input,.input-field .prefix ~ textarea,.input-field .prefix ~ label,.input-field .prefix ~ .validate ~ label,.input-field .prefix ~ .helper-text,.input-field .prefix ~ .autocomplete-content{margin-left:3rem;width:92%;width:calc(100% - 3rem)}.input-field .prefix ~ label{margin-left:3rem}@media only screen and (max-width: 992px){.input-field .prefix ~ input{width:86%;width:calc(100% - 3rem)}}@media only screen and (max-width: 600px){.input-field .prefix ~ input{width:80%;width:calc(100% - 3rem)}}.input-field input[type=search]{display:block;line-height:inherit;-webkit-transition:.3s background-color;transition:.3s background-color}.nav-wrapper .input-field input[type=search]{height:inherit;padding-left:4rem;width:calc(100% - 4rem);border:0;-webkit-box-shadow:none;box-shadow:none}.input-field input[type=search]:focus:not(.browser-default){background-color:#fff;border:0;-webkit-box-shadow:none;box-shadow:none;color:#444}.input-field input[type=search]:focus:not(.browser-default)+label i,.input-field input[type=search]:focus:not(.browser-default) ~ .mdi-navigation-close,.input-field input[type=search]:focus:not(.browser-default) ~ .material-icons{color:#444}.input-field input[type=search]+.label-icon{-webkit-transform:none;transform:none;left:1rem}.input-field input[type=search] ~ .mdi-navigation-close,.input-field input[type=search] ~ .material-icons{position:absolute;top:0;right:1rem;color:transparent;cursor:pointer;font-size:2rem;-webkit-transition:.3s color;transition:.3s color}textarea{width:100%;height:3rem;background-color:transparent}textarea.materialize-textarea{line-height:normal;overflow-y:hidden;padding:.8rem 0 .8rem 0;resize:none;min-height:3rem;-webkit-box-sizing:border-box;box-sizing:border-box}.hiddendiv{visibility:hidden;white-space:pre-wrap;word-wrap:break-word;overflow-wrap:break-word;padding-top:1.2rem;position:absolute;top:0;z-index:-1}.autocomplete-content li .highlight{color:#444}.autocomplete-content li img{height:40px;width:40px;margin:5px 15px}.character-counter{min-height:18px}[type="radio"]:not(:checked),[type="radio"]:checked{position:absolute;opacity:0;pointer-events:none}[type="radio"]:not(:checked)+span,[type="radio"]:checked+span{position:relative;padding-left:35px;cursor:pointer;display:inline-block;height:25px;line-height:25px;font-size:1rem;-webkit-transition:.28s ease;transition:.28s ease;-webkit-user-select:none;-moz-user-select:none;-ms-user-select:none;user-select:none}[type="radio"]+span:before,[type="radio"]+span:after{content:'';position:absolute;left:0;top:0;margin:4px;width:16px;height:16px;z-index:0;-webkit-transition:.28s ease;transition:.28s ease}[type="radio"]:not(:checked)+span:before,[type="radio"]:not(:checked)+span:after,[type="radio"]:checked+span:before,[type="radio"]:checked+span:after,[type="radio"].with-gap:checked+span:before,[type="radio"].with-gap:checked+span:after{border-radius:50%}[type="radio"]:not(:checked)+span:before,[type="radio"]:not(:checked)+span:after{border:2px solid #5a5a5a}[type="radio"]:not(:checked)+span:after{-webkit-transform:scale(0);transform:scale(0)}[type="radio"]:checked+span:before{border:2px solid transparent}[type="radio"]:checked+span:after,[type="radio"].with-gap:checked+span:before,[type="radio"].with-gap:checked+span:after{border:2px solid #26a69a}[type="radio"]:checked+span:after,[type="radio"].with-gap:checked+span:after{background-color:#26a69a}[type="radio"]:checked+span:after{-webkit-transform:scale(1.02);transform:scale(1.02)}[type="radio"].with-gap:checked+span:after{-webkit-transform:scale(0.5);transform:scale(0.5)}[type="radio"].tabbed:focus+span:before{-webkit-box-shadow:0 0 0 10px rgba(0,0,0,0.1);box-shadow:0 0 0 10px rgba(0,0,0,0.1)}[type="radio"].with-gap:disabled:checked+span:before{border:2px solid rgba(0,0,0,0.42)}[type="radio"].with-gap:disabled:checked+span:after{border:none;background-color:rgba(0,0,0,0.42)}[type="radio"]:disabled:not(:checked)+span:before,[type="radio"]:disabled:checked+span:before{background-color:transparent;border-color:rgba(0,0,0,0.42)}[type="radio"]:disabled+span{color:rgba(0,0,0,0.42)}[type="radio"]:disabled:not(:checked)+span:before{border-color:rgba(0,0,0,0.42)}[type="radio"]:disabled:checked+span:after{background-color:rgba(0,0,0,0.42);border-color:#949494}[type="checkbox"]:not(:checked),[type="checkbox"]:checked{position:absolute;opacity:0;pointer-events:none}[type="checkbox"]+span:not(.lever){position:relative;padding-left:35px;cursor:pointer;display:inline-block;height:25px;line-height:25px;font-size:1rem;-webkit-user-select:none;-moz-user-select:none;-ms-user-select:none;user-select:none}[type="checkbox"]+span:not(.lever):before,[type="checkbox"]:not(.filled-in)+span:not(.lever):after{content:'';position:absolute;top:0;left:0;width:18px;height:18px;z-index:0;border:2px solid #5a5a5a;border-radius:1px;margin-top:3px;-webkit-transition:.2s;transition:.2s}[type="checkbox"]:not(.filled-in)+span:not(.lever):after{border:0;-webkit-transform:scale(0);transform:scale(0)}[type="checkbox"]:not(:checked):disabled+span:not(.lever):before{border:none;background-color:rgba(0,0,0,0.42)}[type="checkbox"].tabbed:focus+span:not(.lever):after{-webkit-transform:scale(1);transform:scale(1);border:0;border-radius:50%;-webkit-box-shadow:0 0 0 10px rgba(0,0,0,0.1);box-shadow:0 0 0 10px rgba(0,0,0,0.1);background-color:rgba(0,0,0,0.1)}[type="checkbox"]:checked+span:not(.lever):before{top:-4px;left:-5px;width:12px;height:22px;border-top:2px solid transparent;border-left:2px solid transparent;border-right:2px solid #26a69a;border-bottom:2px solid #26a69a;-webkit-transform:rotate(40deg);transform:rotate(40deg);-webkit-backface-visibility:hidden;backface-visibility:hidden;-webkit-transform-origin:100% 100%;transform-origin:100% 100%}[type="checkbox"]:checked:disabled+span:before{border-right:2px solid rgba(0,0,0,0.42);border-bottom:2px solid rgba(0,0,0,0.42)}[type="checkbox"]:indeterminate+span:not(.lever):before{top:-11px;left:-12px;width:10px;height:22px;border-top:none;border-left:none;border-right:2px solid #26a69a;border-bottom:none;-webkit-transform:rotate(90deg);transform:rotate(90deg);-webkit-backface-visibility:hidden;backface-visibility:hidden;-webkit-transform-origin:100% 100%;transform-origin:100% 100%}[type="checkbox"]:indeterminate:disabled+span:not(.lever):before{border-right:2px solid rgba(0,0,0,0.42);background-color:transparent}[type="checkbox"].filled-in+span:not(.lever):after{border-radius:2px}[type="checkbox"].filled-in+span:not(.lever):before,[type="checkbox"].filled-in+span:not(.lever):after{content:'';left:0;position:absolute;-webkit-transition:border .25s, background-color .25s, width .20s .1s, height .20s .1s, top .20s .1s, left .20s .1s;transition:border .25s, background-color .25s, width .20s .1s, height .20s .1s, top .20s .1s, left .20s .1s;z-index:1}[type="checkbox"].filled-in:not(:checked)+span:not(.lever):before{width:0;height:0;border:3px solid transparent;left:6px;top:10px;-webkit-transform:rotateZ(37deg);transform:rotateZ(37deg);-webkit-transform-origin:100% 100%;transform-origin:100% 100%}[type="checkbox"].filled-in:not(:checked)+span:not(.lever):after{height:20px;width:20px;background-color:transparent;border:2px solid #5a5a5a;top:0px;z-index:0}[type="checkbox"].filled-in:checked+span:not(.lever):before{top:0;left:1px;width:8px;height:13px;border-top:2px solid transparent;border-left:2px solid transparent;border-right:2px solid #fff;border-bottom:2px solid #fff;-webkit-transform:rotateZ(37deg);transform:rotateZ(37deg);-webkit-transform-origin:100% 100%;transform-origin:100% 100%}[type="checkbox"].filled-in:checked+span:not(.lever):after{top:0;width:20px;height:20px;border:2px solid #26a69a;background-color:#26a69a;z-index:0}[type="checkbox"].filled-in.tabbed:focus+span:not(.lever):after{border-radius:2px;border-color:#5a5a5a;background-color:rgba(0,0,0,0.1)}[type="checkbox"].filled-in.tabbed:checked:focus+span:not(.lever):after{border-radius:2px;background-color:#26a69a;border-color:#26a69a}[type="checkbox"].filled-in:disabled:not(:checked)+span:not(.lever):before{background-color:transparent;border:2px solid transparent}[type="checkbox"].filled-in:disabled:not(:checked)+span:not(.lever):after{border-color:transparent;background-color:#949494}[type="checkbox"].filled-in:disabled:checked+span:not(.lever):before{background-color:transparent}[type="checkbox"].filled-in:disabled:checked+span:not(.lever):after{background-color:#949494;border-color:#949494}.switch,.switch *{-webkit-tap-highlight-color:transparent;-webkit-user-select:none;-moz-user-select:none;-ms-user-select:none;user-select:none}.switch label{cursor:pointer}.switch label input[type=checkbox]{opacity:0;width:0;height:0}.switch label input[type=checkbox]:checked+.lever{background-color:#84c7c1}.switch label input[type=checkbox]:checked+.lever:before,.switch label input[type=checkbox]:checked+.lever:after{left:18px}.switch label input[type=checkbox]:checked+.lever:after{background-color:#26a69a}.switch label .lever{content:"";display:inline-block;position:relative;width:36px;height:14px;background-color:rgba(0,0,0,0.38);border-radius:15px;margin-right:10px;-webkit-transition:background 0.3s ease;transition:background 0.3s ease;vertical-align:middle;margin:0 16px}.switch label .lever:before,.switch label .lever:after{content:"";position:absolute;display:inline-block;width:20px;height:20px;border-radius:50%;left:0;top:-3px;-webkit-transition:left 0.3s ease, background .3s ease, -webkit-box-shadow 0.1s ease, -webkit-transform .1s ease;transition:left 0.3s ease, background .3s ease, -webkit-box-shadow 0.1s ease, -webkit-transform .1s ease;transition:left 0.3s ease, background .3s ease, box-shadow 0.1s ease, transform .1s ease;transition:left 0.3s ease, background .3s ease, box-shadow 0.1s ease, transform .1s ease, -webkit-box-shadow 0.1s ease, -webkit-transform .1s ease}.switch label .lever:before{background-color:rgba(38,166,154,0.15)}.switch label .lever:after{background-color:#F1F1F1;-webkit-box-shadow:0px 3px 1px -2px rgba(0,0,0,0.2),0px 2px 2px 0px rgba(0,0,0,0.14),0px 1px 5px 0px rgba(0,0,0,0.12);box-shadow:0px 3px 1px -2px rgba(0,0,0,0.2),0px 2px 2px 0px rgba(0,0,0,0.14),0px 1px 5px 0px rgba(0,0,0,0.12)}input[type=checkbox]:checked:not(:disabled) ~ .lever:active::before,input[type=checkbox]:checked:not(:disabled).tabbed:focus ~ .lever::before{-webkit-transform:scale(2.4);transform:scale(2.4);background-color:rgba(38,166,154,0.15)}input[type=checkbox]:not(:disabled) ~ .lever:active:before,input[type=checkbox]:not(:disabled).tabbed:focus ~ .lever::before{-webkit-transform:scale(2.4);transform:scale(2.4);background-color:rgba(0,0,0,0.08)}.switch input[type=checkbox][disabled]+.lever{cursor:default;background-color:rgba(0,0,0,0.12)}.switch label input[type=checkbox][disabled]+.lever:after,.switch label input[type=checkbox][disabled]:checked+.lever:after{background-color:#949494}select{display:none}select.browser-default{display:block}select{background-color:rgba(255,255,255,0.9);width:100%;padding:5px;border:1px solid #f2f2f2;border-radius:2px;height:3rem}.select-label{position:absolute}.select-wrapper{position:relative}.select-wrapper.valid+label,.select-wrapper.invalid+label{width:100%;pointer-events:none}.select-wrapper input.select-dropdown{position:relative;cursor:pointer;background-color:transparent;border:none;border-bottom:1px solid #9e9e9e;outline:none;height:3rem;line-height:3rem;width:100%;font-size:16px;margin:0 0 8px 0;padding:0;display:block;-webkit-user-select:none;-moz-user-select:none;-ms-user-select:none;user-select:none;z-index:1}.select-wrapper input.select-dropdown:focus{border-bottom:1px solid #26a69a}.select-wrapper .caret{position:absolute;right:0;top:0;bottom:0;margin:auto 0;z-index:0;fill:rgba(0,0,0,0.87)}.select-wrapper+label{position:absolute;top:-26px;font-size:.8rem}select:disabled{color:rgba(0,0,0,0.42)}.select-wrapper.disabled+label{color:rgba(0,0,0,0.42)}.select-wrapper.disabled .caret{fill:rgba(0,0,0,0.42)}.select-wrapper input.select-dropdown:disabled{color:rgba(0,0,0,0.42);cursor:default;-webkit-user-select:none;-moz-user-select:none;-ms-user-select:none;user-select:none}.select-wrapper i{color:rgba(0,0,0,0.3)}.select-dropdown li.disabled,.select-dropdown li.disabled>span,.select-dropdown li.optgroup{color:rgba(0,0,0,0.3);background-color:transparent}body.keyboard-focused .select-dropdown.dropdown-content li:focus{background-color:rgba(0,0,0,0.08)}.select-dropdown.dropdown-content li:hover{background-color:rgba(0,0,0,0.08)}.select-dropdown.dropdown-content li.selected{background-color:rgba(0,0,0,0.03)}.prefix ~ .select-wrapper{margin-left:3rem;width:92%;width:calc(100% - 3rem)}.prefix ~ label{margin-left:3rem}.select-dropdown li img{height:40px;width:40px;margin:5px 15px;float:right}.select-dropdown li.optgroup{border-top:1px solid #eee}.select-dropdown li.optgroup.selected>span{color:rgba(0,0,0,0.7)}.select-dropdown li.optgroup>span{color:rgba(0,0,0,0.4)}.select-dropdown li.optgroup ~ li.optgroup-option{padding-left:1rem}.file-field{position:relative}.file-field .file-path-wrapper{overflow:hidden;padding-left:10px}.file-field input.file-path{width:100%}.file-field .btn,.file-field .btn-large,.file-field .btn-small{float:left;height:3rem;line-height:3rem}.file-field span{cursor:pointer}.file-field input[type=file]{position:absolute;top:0;right:0;left:0;bottom:0;width:100%;margin:0;padding:0;font-size:20px;cursor:pointer;opacity:0;filter:alpha(opacity=0)}.file-field input[type=file]::-webkit-file-upload-button{display:none}.range-field{position:relative}input[type=range],input[type=range]+.thumb{cursor:pointer}input[type=range]{position:relative;background-color:transparent;border:none;outline:none;width:100%;margin:15px 0;padding:0}input[type=range]:focus{outline:none}input[type=range]+.thumb{position:absolute;top:10px;left:0;border:none;height:0;width:0;border-radius:50%;background-color:#26a69a;margin-left:7px;-webkit-transform-origin:50% 50%;transform-origin:50% 50%;-webkit-transform:rotate(-45deg);transform:rotate(-45deg)}input[type=range]+.thumb .value{display:block;width:30px;text-align:center;color:#26a69a;font-size:0;-webkit-transform:rotate(45deg);transform:rotate(45deg)}input[type=range]+.thumb.active{border-radius:50% 50% 50% 0}input[type=range]+.thumb.active .value{color:#fff;margin-left:-1px;margin-top:8px;font-size:10px}input[type=range]{-webkit-appearance:none}input[type=range]::-webkit-slider-runnable-track{height:3px;background:#c2c0c2;border:none}input[type=range]::-webkit-slider-thumb{border:none;height:14px;width:14px;border-radius:50%;background:#26a69a;-webkit-transition:-webkit-box-shadow .3s;transition:-webkit-box-shadow .3s;transition:box-shadow .3s;transition:box-shadow .3s, -webkit-box-shadow .3s;-webkit-appearance:none;background-color:#26a69a;-webkit-transform-origin:50% 50%;transform-origin:50% 50%;margin:-5px 0 0 0}.keyboard-focused input[type=range]:focus:not(.active)::-webkit-slider-thumb{-webkit-box-shadow:0 0 0 10px rgba(38,166,154,0.26);box-shadow:0 0 0 10px rgba(38,166,154,0.26)}input[type=range]{border:1px solid white}input[type=range]::-moz-range-track{height:3px;background:#c2c0c2;border:none}input[type=range]::-moz-focus-inner{border:0}input[type=range]::-moz-range-thumb{border:none;height:14px;width:14px;border-radius:50%;background:#26a69a;-webkit-transition:-webkit-box-shadow .3s;transition:-webkit-box-shadow .3s;transition:box-shadow .3s;transition:box-shadow .3s, -webkit-box-shadow .3s;margin-top:-5px}input[type=range]:-moz-focusring{outline:1px solid #fff;outline-offset:-1px}.keyboard-focused input[type=range]:focus:not(.active)::-moz-range-thumb{box-shadow:0 0 0 10px rgba(38,166,154,0.26)}input[type=range]::-ms-track{height:3px;background:transparent;border-color:transparent;border-width:6px 0;color:transparent}input[type=range]::-ms-fill-lower{background:#777}input[type=range]::-ms-fill-upper{background:#ddd}input[type=range]::-ms-thumb{border:none;height:14px;width:14px;border-radius:50%;background:#26a69a;-webkit-transition:-webkit-box-shadow .3s;transition:-webkit-box-shadow .3s;transition:box-shadow .3s;transition:box-shadow .3s, -webkit-box-shadow .3s}.keyboard-focused input[type=range]:focus:not(.active)::-ms-thumb{box-shadow:0 0 0 10px rgba(38,166,154,0.26)}.table-of-contents.fixed{position:fixed}.table-of-contents li{padding:2px 0}.table-of-contents a{display:inline-block;font-weight:300;color:#757575;padding-left:16px;height:1.5rem;line-height:1.5rem;letter-spacing:.4;display:inline-block}.table-of-contents a:hover{color:#a8a8a8;padding-left:15px;border-left:1px solid #ee6e73}.table-of-contents a.active{font-weight:500;padding-left:14px;border-left:2px solid #ee6e73}.sidenav{position:fixed;width:300px;left:0;top:0;margin:0;-webkit-transform:translateX(-100%);transform:translateX(-100%);height:100%;height:calc(100% + 60px);height:-moz-calc(100%);padding-bottom:60px;background-color:#fff;z-index:999;overflow-y:auto;will-change:transform;-webkit-backface-visibility:hidden;backface-visibility:hidden;-webkit-transform:translateX(-105%);transform:translateX(-105%)}.sidenav.right-aligned{right:0;-webkit-transform:translateX(105%);transform:translateX(105%);left:auto;-webkit-transform:translateX(100%);transform:translateX(100%)}.sidenav .collapsible{margin:0}.sidenav li{float:none;line-height:48px}.sidenav li.active{background-color:rgba(0,0,0,0.05)}.sidenav li>a{color:rgba(0,0,0,0.87);display:block;font-size:14px;font-weight:500;height:48px;line-height:48px;padding:0 32px}.sidenav li>a:hover{background-color:rgba(0,0,0,0.05)}.sidenav li>a.btn,.sidenav li>a.btn-large,.sidenav li>a.btn-small,.sidenav li>a.btn-large,.sidenav li>a.btn-flat,.sidenav li>a.btn-floating{margin:10px 15px}.sidenav li>a.btn,.sidenav li>a.btn-large,.sidenav li>a.btn-small,.sidenav li>a.btn-large,.sidenav li>a.btn-floating{color:#fff}.sidenav li>a.btn-flat{color:#343434}.sidenav li>a.btn:hover,.sidenav li>a.btn-large:hover,.sidenav li>a.btn-small:hover,.sidenav li>a.btn-large:hover{background-color:#2bbbad}.sidenav li>a.btn-floating:hover{background-color:#26a69a}.sidenav li>a>i,.sidenav li>a>[class^="mdi-"],.sidenav li>a li>a>[class*="mdi-"],.sidenav li>a>i.material-icons{float:left;height:48px;line-height:48px;margin:0 32px 0 0;width:24px;color:rgba(0,0,0,0.54)}.sidenav .divider{margin:8px 0 0 0}.sidenav .subheader{cursor:initial;pointer-events:none;color:rgba(0,0,0,0.54);font-size:14px;font-weight:500;line-height:48px}.sidenav .subheader:hover{background-color:transparent}.sidenav .user-view{position:relative;padding:32px 32px 0;margin-bottom:8px}.sidenav .user-view>a{height:auto;padding:0}.sidenav .user-view>a:hover{background-color:transparent}.sidenav .user-view .background{overflow:hidden;position:absolute;top:0;right:0;bottom:0;left:0;z-index:-1}.sidenav .user-view .circle,.sidenav .user-view .name,.sidenav .user-view .email{display:block}.sidenav .user-view .circle{height:64px;width:64px}.sidenav .user-view .name,.sidenav .user-view .email{font-size:14px;line-height:24px}.sidenav .user-view .name{margin-top:16px;font-weight:500}.sidenav .user-view .email{padding-bottom:16px;font-weight:400}.drag-target{height:100%;width:10px;position:fixed;top:0;z-index:998}.drag-target.right-aligned{right:0}.sidenav.sidenav-fixed{left:0;-webkit-transform:translateX(0);transform:translateX(0);position:fixed}.sidenav.sidenav-fixed.right-aligned{right:0;left:auto}@media only screen and (max-width: 992px){.sidenav.sidenav-fixed{-webkit-transform:translateX(-105%);transform:translateX(-105%)}.sidenav.sidenav-fixed.right-aligned{-webkit-transform:translateX(105%);transform:translateX(105%)}.sidenav>a{padding:0 16px}.sidenav .user-view{padding:16px 16px 0}}.sidenav .collapsible-body>ul:not(.collapsible)>li.active,.sidenav.sidenav-fixed .collapsible-body>ul:not(.collapsible)>li.active{background-color:#ee6e73}.sidenav .collapsible-body>ul:not(.collapsible)>li.active a,.sidenav.sidenav-fixed .collapsible-body>ul:not(.collapsible)>li.active a{color:#fff}.sidenav .collapsible-body{padding:0}.sidenav-overlay{position:fixed;top:0;left:0;right:0;opacity:0;height:120vh;background-color:rgba(0,0,0,0.5);z-index:997;display:none}.preloader-wrapper{display:inline-block;position:relative;width:50px;height:50px}.preloader-wrapper.small{width:36px;height:36px}.preloader-wrapper.big{width:64px;height:64px}.preloader-wrapper.active{-webkit-animation:container-rotate 1568ms linear infinite;animation:container-rotate 1568ms linear infinite}@-webkit-keyframes container-rotate{to{-webkit-transform:rotate(360deg)}}@keyframes container-rotate{to{-webkit-transform:rotate(360deg);transform:rotate(360deg)}}.spinner-layer{position:absolute;width:100%;height:100%;opacity:0;border-color:#26a69a}.spinner-blue,.spinner-blue-only{border-color:#4285f4}.spinner-red,.spinner-red-only{border-color:#db4437}.spinner-yellow,.spinner-yellow-only{border-color:#f4b400}.spinner-green,.spinner-green-only{border-color:#0f9d58}.active .spinner-layer.spinner-blue{-webkit-animation:fill-unfill-rotate 5332ms cubic-bezier(0.4, 0, 0.2, 1) infinite both,blue-fade-in-out 5332ms cubic-bezier(0.4, 0, 0.2, 1) infinite both;animation:fill-unfill-rotate 5332ms cubic-bezier(0.4, 0, 0.2, 1) infinite both,blue-fade-in-out 5332ms cubic-bezier(0.4, 0, 0.2, 1) infinite both}.active .spinner-layer.spinner-red{-webkit-animation:fill-unfill-rotate 5332ms cubic-bezier(0.4, 0, 0.2, 1) infinite both,red-fade-in-out 5332ms cubic-bezier(0.4, 0, 0.2, 1) infinite both;animation:fill-unfill-rotate 5332ms cubic-bezier(0.4, 0, 0.2, 1) infinite both,red-fade-in-out 5332ms cubic-bezier(0.4, 0, 0.2, 1) infinite both}.active .spinner-layer.spinner-yellow{-webkit-animation:fill-unfill-rotate 5332ms cubic-bezier(0.4, 0, 0.2, 1) infinite both,yellow-fade-in-out 5332ms cubic-bezier(0.4, 0, 0.2, 1) infinite both;animation:fill-unfill-rotate 5332ms cubic-bezier(0.4, 0, 0.2, 1) infinite both,yellow-fade-in-out 5332ms cubic-bezier(0.4, 0, 0.2, 1) infinite both}.active .spinner-layer.spinner-green{-webkit-animation:fill-unfill-rotate 5332ms cubic-bezier(0.4, 0, 0.2, 1) infinite both,green-fade-in-out 5332ms cubic-bezier(0.4, 0, 0.2, 1) infinite both;animation:fill-unfill-rotate 5332ms cubic-bezier(0.4, 0, 0.2, 1) infinite both,green-fade-in-out 5332ms cubic-bezier(0.4, 0, 0.2, 1) infinite both}.active .spinner-layer,.active .spinner-layer.spinner-blue-only,.active .spinner-layer.spinner-red-only,.active .spinner-layer.spinner-yellow-only,.active .spinner-layer.spinner-green-only{opacity:1;-webkit-animation:fill-unfill-rotate 5332ms cubic-bezier(0.4, 0, 0.2, 1) infinite both;animation:fill-unfill-rotate 5332ms cubic-bezier(0.4, 0, 0.2, 1) infinite both}@-webkit-keyframes fill-unfill-rotate{12.5%{-webkit-transform:rotate(135deg)}25%{-webkit-transform:rotate(270deg)}37.5%{-webkit-transform:rotate(405deg)}50%{-webkit-transform:rotate(540deg)}62.5%{-webkit-transform:rotate(675deg)}75%{-webkit-transform:rotate(810deg)}87.5%{-webkit-transform:rotate(945deg)}to{-webkit-transform:rotate(1080deg)}}@keyframes fill-unfill-rotate{12.5%{-webkit-transform:rotate(135deg);transform:rotate(135deg)}25%{-webkit-transform:rotate(270deg);transform:rotate(270deg)}37.5%{-webkit-transform:rotate(405deg);transform:rotate(405deg)}50%{-webkit-transform:rotate(540deg);transform:rotate(540deg)}62.5%{-webkit-transform:rotate(675deg);transform:rotate(675deg)}75%{-webkit-transform:rotate(810deg);transform:rotate(810deg)}87.5%{-webkit-transform:rotate(945deg);transform:rotate(945deg)}to{-webkit-transform:rotate(1080deg);transform:rotate(1080deg)}}@-webkit-keyframes blue-fade-in-out{from{opacity:1}25%{opacity:1}26%{opacity:0}89%{opacity:0}90%{opacity:1}100%{opacity:1}}@keyframes blue-fade-in-out{from{opacity:1}25%{opacity:1}26%{opacity:0}89%{opacity:0}90%{opacity:1}100%{opacity:1}}@-webkit-keyframes red-fade-in-out{from{opacity:0}15%{opacity:0}25%{opacity:1}50%{opacity:1}51%{opacity:0}}@keyframes red-fade-in-out{from{opacity:0}15%{opacity:0}25%{opacity:1}50%{opacity:1}51%{opacity:0}}@-webkit-keyframes yellow-fade-in-out{from{opacity:0}40%{opacity:0}50%{opacity:1}75%{opacity:1}76%{opacity:0}}@keyframes yellow-fade-in-out{from{opacity:0}40%{opacity:0}50%{opacity:1}75%{opacity:1}76%{opacity:0}}@-webkit-keyframes green-fade-in-out{from{opacity:0}65%{opacity:0}75%{opacity:1}90%{opacity:1}100%{opacity:0}}@keyframes green-fade-in-out{from{opacity:0}65%{opacity:0}75%{opacity:1}90%{opacity:1}100%{opacity:0}}.gap-patch{position:absolute;top:0;left:45%;width:10%;height:100%;overflow:hidden;border-color:inherit}.gap-patch .circle{width:1000%;left:-450%}.circle-clipper{display:inline-block;position:relative;width:50%;height:100%;overflow:hidden;border-color:inherit}.circle-clipper .circle{width:200%;height:100%;border-width:3px;border-style:solid;border-color:inherit;border-bottom-color:transparent !important;border-radius:50%;-webkit-animation:none;animation:none;position:absolute;top:0;right:0;bottom:0}.circle-clipper.left .circle{left:0;border-right-color:transparent !important;-webkit-transform:rotate(129deg);transform:rotate(129deg)}.circle-clipper.right .circle{left:-100%;border-left-color:transparent !important;-webkit-transform:rotate(-129deg);transform:rotate(-129deg)}.active .circle-clipper.left .circle{-webkit-animation:left-spin 1333ms cubic-bezier(0.4, 0, 0.2, 1) infinite both;animation:left-spin 1333ms cubic-bezier(0.4, 0, 0.2, 1) infinite both}.active .circle-clipper.right .circle{-webkit-animation:right-spin 1333ms cubic-bezier(0.4, 0, 0.2, 1) infinite both;animation:right-spin 1333ms cubic-bezier(0.4, 0, 0.2, 1) infinite both}@-webkit-keyframes left-spin{from{-webkit-transform:rotate(130deg)}50%{-webkit-transform:rotate(-5deg)}to{-webkit-transform:rotate(130deg)}}@keyframes left-spin{from{-webkit-transform:rotate(130deg);transform:rotate(130deg)}50%{-webkit-transform:rotate(-5deg);transform:rotate(-5deg)}to{-webkit-transform:rotate(130deg);transform:rotate(130deg)}}@-webkit-keyframes right-spin{from{-webkit-transform:rotate(-130deg)}50%{-webkit-transform:rotate(5deg)}to{-webkit-transform:rotate(-130deg)}}@keyframes right-spin{from{-webkit-transform:rotate(-130deg);transform:rotate(-130deg)}50%{-webkit-transform:rotate(5deg);transform:rotate(5deg)}to{-webkit-transform:rotate(-130deg);transform:rotate(-130deg)}}#spinnerContainer.cooldown{-webkit-animation:container-rotate 1568ms linear infinite,fade-out 400ms cubic-bezier(0.4, 0, 0.2, 1);animation:container-rotate 1568ms linear infinite,fade-out 400ms cubic-bezier(0.4, 0, 0.2, 1)}@-webkit-keyframes fade-out{from{opacity:1}to{opacity:0}}@keyframes fade-out{from{opacity:1}to{opacity:0}}.slider{position:relative;height:400px;width:100%}.slider.fullscreen{height:100%;width:100%;position:absolute;top:0;left:0;right:0;bottom:0}.slider.fullscreen ul.slides{height:100%}.slider.fullscreen ul.indicators{z-index:2;bottom:30px}.slider .slides{background-color:#9e9e9e;margin:0;height:400px}.slider .slides li{opacity:0;position:absolute;top:0;left:0;z-index:1;width:100%;height:inherit;overflow:hidden}.slider .slides li img{height:100%;width:100%;background-size:cover;background-position:center}.slider .slides li .caption{color:#fff;position:absolute;top:15%;left:15%;width:70%;opacity:0}.slider .slides li .caption p{color:#e0e0e0}.slider .slides li.active{z-index:2}.slider .indicators{position:absolute;text-align:center;left:0;right:0;bottom:0;margin:0}.slider .indicators .indicator-item{display:inline-block;position:relative;cursor:pointer;height:16px;width:16px;margin:0 12px;background-color:#e0e0e0;-webkit-transition:background-color .3s;transition:background-color .3s;border-radius:50%}.slider .indicators .indicator-item.active{background-color:#4CAF50}.carousel{overflow:hidden;position:relative;width:100%;height:400px;-webkit-perspective:500px;perspective:500px;-webkit-transform-style:preserve-3d;transform-style:preserve-3d;-webkit-transform-origin:0% 50%;transform-origin:0% 50%}.carousel.carousel-slider{top:0;left:0}.carousel.carousel-slider .carousel-fixed-item{position:absolute;left:0;right:0;bottom:20px;z-index:1}.carousel.carousel-slider .carousel-fixed-item.with-indicators{bottom:68px}.carousel.carousel-slider .carousel-item{width:100%;height:100%;min-height:400px;position:absolute;top:0;left:0}.carousel.carousel-slider .carousel-item h2{font-size:24px;font-weight:500;line-height:32px}.carousel.carousel-slider .carousel-item p{font-size:15px}.carousel .carousel-item{visibility:hidden;width:200px;height:200px;position:absolute;top:0;left:0}.carousel .carousel-item>img{width:100%}.carousel .indicators{position:absolute;text-align:center;left:0;right:0;bottom:0;margin:0}.carousel .indicators .indicator-item{display:inline-block;position:relative;cursor:pointer;height:8px;width:8px;margin:24px 4px;background-color:rgba(255,255,255,0.5);-webkit-transition:background-color .3s;transition:background-color .3s;border-radius:50%}.carousel .indicators .indicator-item.active{background-color:#fff}.carousel.scrolling .carousel-item .materialboxed,.carousel .carousel-item:not(.active) .materialboxed{pointer-events:none}.tap-target-wrapper{width:800px;height:800px;position:fixed;z-index:1000;visibility:hidden;-webkit-transition:visibility 0s .3s;transition:visibility 0s .3s}.tap-target-wrapper.open{visibility:visible;-webkit-transition:visibility 0s;transition:visibility 0s}.tap-target-wrapper.open .tap-target{-webkit-transform:scale(1);transform:scale(1);opacity:.95;-webkit-transition:opacity 0.3s cubic-bezier(0.42, 0, 0.58, 1),-webkit-transform 0.3s cubic-bezier(0.42, 0, 0.58, 1);transition:opacity 0.3s cubic-bezier(0.42, 0, 0.58, 1),-webkit-transform 0.3s cubic-bezier(0.42, 0, 0.58, 1);transition:transform 0.3s cubic-bezier(0.42, 0, 0.58, 1),opacity 0.3s cubic-bezier(0.42, 0, 0.58, 1);transition:transform 0.3s cubic-bezier(0.42, 0, 0.58, 1),opacity 0.3s cubic-bezier(0.42, 0, 0.58, 1),-webkit-transform 0.3s cubic-bezier(0.42, 0, 0.58, 1)}.tap-target-wrapper.open .tap-target-wave::before{-webkit-transform:scale(1);transform:scale(1)}.tap-target-wrapper.open .tap-target-wave::after{visibility:visible;-webkit-animation:pulse-animation 1s cubic-bezier(0.24, 0, 0.38, 1) infinite;animation:pulse-animation 1s cubic-bezier(0.24, 0, 0.38, 1) infinite;-webkit-transition:opacity .3s, visibility 0s 1s, -webkit-transform .3s;transition:opacity .3s, visibility 0s 1s, -webkit-transform .3s;transition:opacity .3s, transform .3s, visibility 0s 1s;transition:opacity .3s, transform .3s, visibility 0s 1s, -webkit-transform .3s}.tap-target{position:absolute;font-size:1rem;border-radius:50%;background-color:#ee6e73;-webkit-box-shadow:0 20px 20px 0 rgba(0,0,0,0.14),0 10px 50px 0 rgba(0,0,0,0.12),0 30px 10px -20px rgba(0,0,0,0.2);box-shadow:0 20px 20px 0 rgba(0,0,0,0.14),0 10px 50px 0 rgba(0,0,0,0.12),0 30px 10px -20px rgba(0,0,0,0.2);width:100%;height:100%;opacity:0;-webkit-transform:scale(0);transform:scale(0);-webkit-transition:opacity 0.3s cubic-bezier(0.42, 0, 0.58, 1),-webkit-transform 0.3s cubic-bezier(0.42, 0, 0.58, 1);transition:opacity 0.3s cubic-bezier(0.42, 0, 0.58, 1),-webkit-transform 0.3s cubic-bezier(0.42, 0, 0.58, 1);transition:transform 0.3s cubic-bezier(0.42, 0, 0.58, 1),opacity 0.3s cubic-bezier(0.42, 0, 0.58, 1);transition:transform 0.3s cubic-bezier(0.42, 0, 0.58, 1),opacity 0.3s cubic-bezier(0.42, 0, 0.58, 1),-webkit-transform 0.3s cubic-bezier(0.42, 0, 0.58, 1)}.tap-target-content{position:relative;display:table-cell}.tap-target-wave{position:absolute;border-radius:50%;z-index:10001}.tap-target-wave::before,.tap-target-wave::after{content:'';display:block;position:absolute;width:100%;height:100%;border-radius:50%;background-color:#ffffff}.tap-target-wave::before{-webkit-transform:scale(0);transform:scale(0);-webkit-transition:-webkit-transform .3s;transition:-webkit-transform .3s;transition:transform .3s;transition:transform .3s, -webkit-transform .3s}.tap-target-wave::after{visibility:hidden;-webkit-transition:opacity .3s, visibility 0s, -webkit-transform .3s;transition:opacity .3s, visibility 0s, -webkit-transform .3s;transition:opacity .3s, transform .3s, visibility 0s;transition:opacity .3s, transform .3s, visibility 0s, -webkit-transform .3s;z-index:-1}.tap-target-origin{top:50%;left:50%;-webkit-transform:translate(-50%, -50%);transform:translate(-50%, -50%);z-index:10002;position:absolute !important}.tap-target-origin:not(.btn):not(.btn-large):not(.btn-small),.tap-target-origin:not(.btn):not(.btn-large):not(.btn-small):hover{background:none}@media only screen and (max-width: 600px){.tap-target,.tap-target-wrapper{width:600px;height:600px}}.pulse{overflow:visible;position:relative}.pulse::before{content:'';display:block;position:absolute;width:100%;height:100%;top:0;left:0;background-color:inherit;border-radius:inherit;-webkit-transition:opacity .3s, -webkit-transform .3s;transition:opacity .3s, -webkit-transform .3s;transition:opacity .3s, transform .3s;transition:opacity .3s, transform .3s, -webkit-transform .3s;-webkit-animation:pulse-animation 1s cubic-bezier(0.24, 0, 0.38, 1) infinite;animation:pulse-animation 1s cubic-bezier(0.24, 0, 0.38, 1) infinite;z-index:-1}@-webkit-keyframes pulse-animation{0%{opacity:1;-webkit-transform:scale(1);transform:scale(1)}50%{opacity:0;-webkit-transform:scale(1.5);transform:scale(1.5)}100%{opacity:0;-webkit-transform:scale(1.5);transform:scale(1.5)}}@keyframes pulse-animation{0%{opacity:1;-webkit-transform:scale(1);transform:scale(1)}50%{opacity:0;-webkit-transform:scale(1.5);transform:scale(1.5)}100%{opacity:0;-webkit-transform:scale(1.5);transform:scale(1.5)}}.datepicker-modal{max-width:325px;min-width:300px;max-height:none}.datepicker-container.modal-content{display:-webkit-box;display:-webkit-flex;display:-ms-flexbox;display:flex;-webkit-box-orient:vertical;-webkit-box-direction:normal;-webkit-flex-direction:column;-ms-flex-direction:column;flex-direction:column;padding:0}.datepicker-controls{display:-webkit-box;display:-webkit-flex;display:-ms-flexbox;display:flex;-webkit-box-pack:justify;-webkit-justify-content:space-between;-ms-flex-pack:justify;justify-content:space-between;width:280px;margin:0 auto}.datepicker-controls .selects-container{display:-webkit-box;display:-webkit-flex;display:-ms-flexbox;display:flex}.datepicker-controls .select-wrapper input{border-bottom:none;text-align:center;margin:0}.datepicker-controls .select-wrapper input:focus{border-bottom:none}.datepicker-controls .select-wrapper .caret{display:none}.datepicker-controls .select-year input{width:50px}.datepicker-controls .select-month input{width:70px}.month-prev,.month-next{margin-top:4px;cursor:pointer;background-color:transparent;border:none}.datepicker-date-display{-webkit-box-flex:1;-webkit-flex:1 auto;-ms-flex:1 auto;flex:1 auto;background-color:#26a69a;color:#fff;padding:20px 22px;font-weight:500}.datepicker-date-display .year-text{display:block;font-size:1.5rem;line-height:25px;color:rgba(255,255,255,0.7)}.datepicker-date-display .date-text{display:block;font-size:2.8rem;line-height:47px;font-weight:500}.datepicker-calendar-container{-webkit-box-flex:2.5;-webkit-flex:2.5 auto;-ms-flex:2.5 auto;flex:2.5 auto}.datepicker-table{width:280px;font-size:1rem;margin:0 auto}.datepicker-table thead{border-bottom:none}.datepicker-table th{padding:10px 5px;text-align:center}.datepicker-table tr{border:none}.datepicker-table abbr{text-decoration:none;color:#999}.datepicker-table td{border-radius:50%;padding:0}.datepicker-table td.is-today{color:#26a69a}.datepicker-table td.is-selected{background-color:#26a69a;color:#fff}.datepicker-table td.is-outside-current-month,.datepicker-table td.is-disabled{color:rgba(0,0,0,0.3);pointer-events:none}.datepicker-day-button{background-color:transparent;border:none;line-height:38px;display:block;width:100%;border-radius:50%;padding:0 5px;cursor:pointer;color:inherit}.datepicker-day-button:focus{background-color:rgba(43,161,150,0.25)}.datepicker-footer{width:280px;margin:0 auto;padding-bottom:5px;display:-webkit-box;display:-webkit-flex;display:-ms-flexbox;display:flex;-webkit-box-pack:justify;-webkit-justify-content:space-between;-ms-flex-pack:justify;justify-content:space-between}.datepicker-cancel,.datepicker-clear,.datepicker-today,.datepicker-done{color:#26a69a;padding:0 1rem}.datepicker-clear{color:#F44336}@media only screen and (min-width: 601px){.datepicker-modal{max-width:625px}.datepicker-container.modal-content{-webkit-box-orient:horizontal;-webkit-box-direction:normal;-webkit-flex-direction:row;-ms-flex-direction:row;flex-direction:row}.datepicker-date-display{-webkit-box-flex:0;-webkit-flex:0 1 270px;-ms-flex:0 1 270px;flex:0 1 270px}.datepicker-controls,.datepicker-table,.datepicker-footer{width:320px}.datepicker-day-button{line-height:44px}}.timepicker-modal{max-width:325px;max-height:none}.timepicker-container.modal-content{display:-webkit-box;display:-webkit-flex;display:-ms-flexbox;display:flex;-webkit-box-orient:vertical;-webkit-box-direction:normal;-webkit-flex-direction:column;-ms-flex-direction:column;flex-direction:column;padding:0}.text-primary{color:#fff}.timepicker-digital-display{-webkit-box-flex:1;-webkit-flex:1 auto;-ms-flex:1 auto;flex:1 auto;background-color:#26a69a;padding:10px;font-weight:300}.timepicker-text-container{font-size:4rem;font-weight:bold;text-align:center;color:rgba(255,255,255,0.6);font-weight:400;position:relative;-webkit-user-select:none;-moz-user-select:none;-ms-user-select:none;user-select:none}.timepicker-span-hours,.timepicker-span-minutes,.timepicker-span-am-pm div{cursor:pointer}.timepicker-span-hours{margin-right:3px}.timepicker-span-minutes{margin-left:3px}.timepicker-display-am-pm{font-size:1.3rem;position:absolute;right:1rem;bottom:1rem;font-weight:400}.timepicker-analog-display{-webkit-box-flex:2.5;-webkit-flex:2.5 auto;-ms-flex:2.5 auto;flex:2.5 auto}.timepicker-plate{background-color:#eee;border-radius:50%;width:270px;height:270px;overflow:visible;position:relative;margin:auto;margin-top:25px;margin-bottom:5px;-webkit-user-select:none;-moz-user-select:none;-ms-user-select:none;user-select:none}.timepicker-canvas,.timepicker-dial{position:absolute;left:0;right:0;top:0;bottom:0}.timepicker-minutes{visibility:hidden}.timepicker-tick{border-radius:50%;color:rgba(0,0,0,0.87);line-height:40px;text-align:center;width:40px;height:40px;position:absolute;cursor:pointer;font-size:15px}.timepicker-tick.active,.timepicker-tick:hover{background-color:rgba(38,166,154,0.25)}.timepicker-dial{-webkit-transition:opacity 350ms, -webkit-transform 350ms;transition:opacity 350ms, -webkit-transform 350ms;transition:transform 350ms, opacity 350ms;transition:transform 350ms, opacity 350ms, -webkit-transform 350ms}.timepicker-dial-out{opacity:0}.timepicker-dial-out.timepicker-hours{-webkit-transform:scale(1.1, 1.1);transform:scale(1.1, 1.1)}.timepicker-dial-out.timepicker-minutes{-webkit-transform:scale(0.8, 0.8);transform:scale(0.8, 0.8)}.timepicker-canvas{-webkit-transition:opacity 175ms;transition:opacity 175ms}.timepicker-canvas line{stroke:#26a69a;stroke-width:4;stroke-linecap:round}.timepicker-canvas-out{opacity:0.25}.timepicker-canvas-bearing{stroke:none;fill:#26a69a}.timepicker-canvas-bg{stroke:none;fill:#26a69a}.timepicker-footer{margin:0 auto;padding:5px 1rem;display:-webkit-box;display:-webkit-flex;display:-ms-flexbox;display:flex;-webkit-box-pack:justify;-webkit-justify-content:space-between;-ms-flex-pack:justify;justify-content:space-between}.timepicker-clear{color:#F44336}.timepicker-close{color:#26a69a}.timepicker-clear,.timepicker-close{padding:0 20px}@media only screen and (min-width: 601px){.timepicker-modal{max-width:600px}.timepicker-container.modal-content{-webkit-box-orient:horizontal;-webkit-box-direction:normal;-webkit-flex-direction:row;-ms-flex-direction:row;flex-direction:row}.timepicker-text-container{top:32%}.timepicker-display-am-pm{position:relative;right:auto;bottom:auto;text-align:center;margin-top:1.2rem}} diff --git a/docs/en/1.1b2/_static/favicon.ico b/docs/en/1.1b2/_static/favicon.ico new file mode 100644 index 0000000..07b38bc Binary files /dev/null and b/docs/en/1.1b2/_static/favicon.ico differ diff --git a/docs/en/1.1b2/_static/images/OK.png b/docs/en/1.1b2/_static/images/OK.png new file mode 100644 index 0000000..81f5433 Binary files /dev/null and b/docs/en/1.1b2/_static/images/OK.png differ diff --git a/docs/en/1.1b2/_static/images/aha.png b/docs/en/1.1b2/_static/images/aha.png new file mode 100644 index 0000000..a421799 Binary files /dev/null and b/docs/en/1.1b2/_static/images/aha.png differ diff --git a/docs/en/1.1b2/_static/images/box-bg-dec-2.svg b/docs/en/1.1b2/_static/images/box-bg-dec-2.svg new file mode 100644 index 0000000..0c1e246 --- /dev/null +++ b/docs/en/1.1b2/_static/images/box-bg-dec-2.svg @@ -0,0 +1,21 @@ + + diff --git a/docs/en/1.1b2/_static/images/box-bg-dec-3.svg b/docs/en/1.1b2/_static/images/box-bg-dec-3.svg new file mode 100644 index 0000000..0d757ca --- /dev/null +++ b/docs/en/1.1b2/_static/images/box-bg-dec-3.svg @@ -0,0 +1,25 @@ + + diff --git a/docs/en/1.1b2/_static/images/box-bg-dec.svg b/docs/en/1.1b2/_static/images/box-bg-dec.svg new file mode 100644 index 0000000..a6e38d5 --- /dev/null +++ b/docs/en/1.1b2/_static/images/box-bg-dec.svg @@ -0,0 +1,21 @@ + + diff --git a/docs/en/1.1b2/_static/images/explanation-logo.svg b/docs/en/1.1b2/_static/images/explanation-logo.svg new file mode 100644 index 0000000..98df7c3 --- /dev/null +++ b/docs/en/1.1b2/_static/images/explanation-logo.svg @@ -0,0 +1,20 @@ + + \ No newline at end of file diff --git a/docs/en/1.1b2/_static/images/fighting.png b/docs/en/1.1b2/_static/images/fighting.png new file mode 100644 index 0000000..a7f6ddd Binary files /dev/null and b/docs/en/1.1b2/_static/images/fighting.png differ diff --git a/docs/en/1.1b2/_static/images/hmm.png b/docs/en/1.1b2/_static/images/hmm.png new file mode 100644 index 0000000..8b60eb6 Binary files /dev/null and b/docs/en/1.1b2/_static/images/hmm.png differ diff --git a/docs/en/1.1b2/_static/images/how-to-icon.svg b/docs/en/1.1b2/_static/images/how-to-icon.svg new file mode 100644 index 0000000..6506741 --- /dev/null +++ b/docs/en/1.1b2/_static/images/how-to-icon.svg @@ -0,0 +1,24 @@ + + \ No newline at end of file diff --git a/docs/en/1.1b2/_static/images/icon-hint.svg b/docs/en/1.1b2/_static/images/icon-hint.svg new file mode 100644 index 0000000..db86c44 --- /dev/null +++ b/docs/en/1.1b2/_static/images/icon-hint.svg @@ -0,0 +1,27 @@ + + \ No newline at end of file diff --git a/docs/en/1.1b2/_static/images/icon-info.svg b/docs/en/1.1b2/_static/images/icon-info.svg new file mode 100644 index 0000000..c4690a0 --- /dev/null +++ b/docs/en/1.1b2/_static/images/icon-info.svg @@ -0,0 +1,27 @@ + + \ No newline at end of file diff --git a/docs/en/1.1b2/_static/images/icon-note.svg b/docs/en/1.1b2/_static/images/icon-note.svg new file mode 100644 index 0000000..03308b0 --- /dev/null +++ b/docs/en/1.1b2/_static/images/icon-note.svg @@ -0,0 +1,21 @@ + + \ No newline at end of file diff --git a/docs/en/1.1b2/_static/images/icon-warning.svg b/docs/en/1.1b2/_static/images/icon-warning.svg new file mode 100644 index 0000000..4e3ea02 --- /dev/null +++ b/docs/en/1.1b2/_static/images/icon-warning.svg @@ -0,0 +1,29 @@ + + \ No newline at end of file diff --git a/docs/en/1.1b2/_static/images/language.svg b/docs/en/1.1b2/_static/images/language.svg new file mode 100644 index 0000000..b61c7d4 --- /dev/null +++ b/docs/en/1.1b2/_static/images/language.svg @@ -0,0 +1,16 @@ + + \ No newline at end of file diff --git a/docs/en/1.1b2/_static/images/reference-logo.svg b/docs/en/1.1b2/_static/images/reference-logo.svg new file mode 100644 index 0000000..b79d156 --- /dev/null +++ b/docs/en/1.1b2/_static/images/reference-logo.svg @@ -0,0 +1,22 @@ + + \ No newline at end of file diff --git a/docs/en/1.1b2/_static/images/tutorials-icon.svg b/docs/en/1.1b2/_static/images/tutorials-icon.svg new file mode 100644 index 0000000..ff76008 --- /dev/null +++ b/docs/en/1.1b2/_static/images/tutorials-icon.svg @@ -0,0 +1,21 @@ + + \ No newline at end of file diff --git a/docs/en/1.1b2/_static/js/documentation_options.js b/docs/en/1.1b2/_static/js/documentation_options.js new file mode 100644 index 0000000..092c7e1 --- /dev/null +++ b/docs/en/1.1b2/_static/js/documentation_options.js @@ -0,0 +1,12 @@ +var DOCUMENTATION_OPTIONS = { + URL_ROOT: document.getElementById("documentation_options").getAttribute('data-url_root'), + VERSION: '1.1.0b2', + LANGUAGE: 'en', + COLLAPSE_INDEX: false, + BUILDER: 'html', + FILE_SUFFIX: '.html', + LINK_SUFFIX: '.html', + HAS_SOURCE: true, + SOURCELINK_SUFFIX: '.txt', + NAVIGATION_WITH_KEYS: false +}; \ No newline at end of file diff --git a/docs/en/1.1b2/_static/js/gino.js b/docs/en/1.1b2/_static/js/gino.js new file mode 100644 index 0000000..1690ada --- /dev/null +++ b/docs/en/1.1b2/_static/js/gino.js @@ -0,0 +1,642 @@ +$u = _.noConflict(); + +function splitQuery(query) { + return query.split(/\s+/); +} + +jQuery.fn.highlightText = function(text, className) { + function highlight(node, addItems) { + if (node.nodeType === 3) { + var val = node.nodeValue; + var pos = val.toLowerCase().indexOf(text); + if (pos >= 0 && + !jQuery(node.parentNode).hasClass(className) && + !jQuery(node.parentNode).hasClass("nohighlight")) { + var span; + var isInSVG = jQuery(node).closest("body, svg, foreignObject").is("svg"); + if (isInSVG) { + span = document.createElementNS("http://www.w3.org/2000/svg", "tspan"); + } else { + span = document.createElement("span"); + span.className = className; + } + span.appendChild(document.createTextNode(val.substr(pos, text.length))); + node.parentNode.insertBefore(span, node.parentNode.insertBefore( + document.createTextNode(val.substr(pos + text.length)), + node.nextSibling)); + node.nodeValue = val.substr(0, pos); + if (isInSVG) { + var rect = document.createElementNS("http://www.w3.org/2000/svg", "rect"); + var bbox = node.parentElement.getBBox(); + rect.x.baseVal.value = bbox.x; + rect.y.baseVal.value = bbox.y; + rect.width.baseVal.value = bbox.width; + rect.height.baseVal.value = bbox.height; + rect.setAttribute('class', className); + addItems.push({ + "parent": node.parentNode, + "target": rect}); + } + } + } + else if (!jQuery(node).is("button, select, textarea")) { + jQuery.each(node.childNodes, function() { + highlight(this, addItems); + }); + } + } + var addItems = []; + var result = this.each(function() { + highlight(this, addItems); + }); + for (var i = 0; i < addItems.length; ++i) { + jQuery(addItems[i].parent).before(addItems[i].target); + } + return result; +}; + +var Scorer = { + // Implement the following function to further tweak the score for each result + // The function takes a result array [filename, title, anchor, descr, score] + // and returns the new score. + /* + score: function(result) { + return result[4]; + }, + */ + + // query matches the full name of an object + objNameMatch: 11, + // or matches in the last dotted part of the object name + objPartialMatch: 6, + // Additive scores depending on the priority of the object + objPrio: {0: 15, // used to be importantResults + 1: 5, // used to be objectResults + 2: -5}, // used to be unimportantResults + // Used when the priority is not in the mapping. + objPrioDefault: 0, + + // query found in title + title: 15, + partialTitle: 7, + // query found in terms + term: 5, + partialTerm: 2 +}; + +var Search = { + _index : null, + + setIndex: function(index) { + this._index = index; + }, + + performObjectSearch : function(object, otherterms) { + var filenames = this._index.filenames; + var docnames = this._index.docnames; + var objects = this._index.objects; + var objnames = this._index.objnames; + var titles = this._index.titles; + + var i; + var results = []; + + for (var prefix in objects) { + for (var name in objects[prefix]) { + var fullname = (prefix ? prefix + '.' : '') + name; + var fullnameLower = fullname.toLowerCase() + if (fullnameLower.indexOf(object) > -1) { + var score = 0; + var parts = fullnameLower.split('.'); + // check for different match types: exact matches of full name or + // "last name" (i.e. last dotted part) + if (fullnameLower == object || parts[parts.length - 1] == object) { + score += Scorer.objNameMatch; + // matches in last name + } else if (parts[parts.length - 1].indexOf(object) > -1) { + score += Scorer.objPartialMatch; + } + var match = objects[prefix][name]; + var objname = objnames[match[1]][2]; + var title = titles[match[0]]; + // If more than one term searched for, we require other words to be + // found in the name/title/description + if (otherterms.length > 0) { + var haystack = (prefix + ' ' + name + ' ' + + objname + ' ' + title).toLowerCase(); + var allfound = true; + for (i = 0; i < otherterms.length; i++) { + if (haystack.indexOf(otherterms[i]) == -1) { + allfound = false; + break; + } + } + if (!allfound) { + continue; + } + } + var descr = objname + (', in ') + title; + + var anchor = match[3]; + if (anchor === '') + anchor = fullname; + else if (anchor == '-') + anchor = objnames[match[1]][1] + '-' + fullname; + // add custom score for some objects according to scorer + if (Scorer.objPrio.hasOwnProperty(match[2])) { + score += Scorer.objPrio[match[2]]; + } else { + score += Scorer.objPrioDefault; + } + results.push([docnames[match[0]], fullname, '#'+anchor, descr, score, filenames[match[0]]]); + } + } + } + + return results; + }, + + /** + * search for full-text terms in the index + */ + performTermsSearch : function(searchterms, excluded, terms, titleterms) { + var docnames = this._index.docnames; + var filenames = this._index.filenames; + var titles = this._index.titles; + + var i, j, file; + var fileMap = {}; + var scoreMap = {}; + var results = []; + + // perform the search on the required terms + for (i = 0; i < searchterms.length; i++) { + var word = searchterms[i]; + var files = []; + var _o = [ + {files: terms[word], score: Scorer.term}, + {files: titleterms[word], score: Scorer.title} + ]; + // add support for partial matches + if (word.length > 2) { + for (var w in terms) { + if (w.match(word) && !terms[word]) { + _o.push({files: terms[w], score: Scorer.partialTerm}) + } + } + for (var w in titleterms) { + if (w.match(word) && !titleterms[word]) { + _o.push({files: titleterms[w], score: Scorer.partialTitle}) + } + } + } + + // no match but word was a required one + if ($u.every(_o, function(o){return o.files === undefined;})) { + break; + } + // found search word in contents + $u.each(_o, function(o) { + var _files = o.files; + if (_files === undefined) + return + + if (_files.length === undefined) + _files = [_files]; + files = files.concat(_files); + + // set score for the word in each file to Scorer.term + for (j = 0; j < _files.length; j++) { + file = _files[j]; + if (!(file in scoreMap)) + scoreMap[file] = {}; + scoreMap[file][word] = o.score; + } + }); + + // create the mapping + for (j = 0; j < files.length; j++) { + file = files[j]; + if (file in fileMap && fileMap[file].indexOf(word) === -1) + fileMap[file].push(word); + else + fileMap[file] = [word]; + } + } + + // now check if the files don't contain excluded terms + for (file in fileMap) { + var valid = true; + + // check if all requirements are matched + var filteredTermCount = // as search terms with length < 3 are discarded: ignore + searchterms.filter(function(term){return term.length > 2}).length + if ( + fileMap[file].length != searchterms.length && + fileMap[file].length != filteredTermCount + ) continue; + + // ensure that none of the excluded terms is in the search result + for (i = 0; i < excluded.length; i++) { + if (terms[excluded[i]] == file || + titleterms[excluded[i]] == file || + $u.contains(terms[excluded[i]] || [], file) || + $u.contains(titleterms[excluded[i]] || [], file)) { + valid = false; + break; + } + } + + // if we have still a valid result we can add it to the result list + if (valid) { + // select one (max) score for the file. + // for better ranking, we should calculate ranking by using words statistics like basic tf-idf... + var score = $u.max($u.map(fileMap[file], function(w){return scoreMap[file][w]})); + results.push([docnames[file], titles[file], '', null, score, filenames[file]]); + } + } + return results; + }, + + /** + * helper function to return a node containing the + * search summary for a given text. keywords is a list + * of stemmed words, hlwords is the list of normal, unstemmed + * words. the first one is used to find the occurrence, the + * latter for highlighting it. + */ + makeSearchSummary : function(htmlText, keywords, hlwords) { + var text = Search.htmlToText(htmlText); + var textLower = text.toLowerCase(); + var start = 0; + $.each(keywords, function() { + var i = textLower.indexOf(this.toLowerCase()); + if (i > -1) + start = i; + }); + start = Math.max(start - 120, 0); + var excerpt = ((start > 0) ? '...' : '') + + $.trim(text.substr(start, 240)) + + ((start + 240 - text.length) ? '...' : ''); + var rv = $('

' + loc.toUpperCase() + '

' + langNames[loc] + '

0.8

' + ver + '

"],col:[2,"","

"],tr:[2,"","

"],td:[3,"","

"],_default:[0,"",""]};function ve(e,t){var n;return n="undefined"!=typeof e.getElementsByTagName?e.getElementsByTagName(t||"*"):"undefined"!=typeof e.querySelectorAll?e.querySelectorAll(t||"*"):[],void 0===t||t&&A(e,t)?k.merge([e],n):n}function ye(e,t){for(var n=0,r=e.length;nx",y.noCloneChecked=!!me.cloneNode(!0).lastChild.defaultValue;var Te=/^key/,Ce=/^(?:mouse|pointer|contextmenu|drag|drop)|click/,Ee=/^([^.]*)(?:\.(.+)|)/;function ke(){return!0}function Se(){return!1}function Ne(e,t){return e===function(){try{return E.activeElement}catch(e){}}()==("focus"===t)}function Ae(e,t,n,r,i,o){var a,s;if("object"==typeof t){for(s in"string"!=typeof n&&(r=r||n,n=void 0),t)Ae(e,s,n,r,t[s],o);return e}if(null==r&&null==i?(i=n,r=n=void 0):null==i&&("string"==typeof n?(i=r,r=void 0):(i=r,r=n,n=void 0)),!1===i)i=Se;else if(!i)return e;return 1===o&&(a=i,(i=function(e){return k().off(e),a.apply(this,arguments)}).guid=a.guid||(a.guid=k.guid++)),e.each(function(){k.event.add(this,t,i,r,n)})}function De(e,i,o){o?(Q.set(e,i,!1),k.event.add(e,i,{namespace:!1,handler:function(e){var t,n,r=Q.get(this,i);if(1&e.isTrigger&&this[i]){if(r.length)(k.event.special[i]||{}).delegateType&&e.stopPropagation();else if(r=s.call(arguments),Q.set(this,i,r),t=o(this,i),this[i](),r!==(n=Q.get(this,i))||t?Q.set(this,i,!1):n={},r!==n)return e.stopImmediatePropagation(),e.preventDefault(),n.value}else r.length&&(Q.set(this,i,{value:k.event.trigger(k.extend(r[0],k.Event.prototype),r.slice(1),this)}),e.stopImmediatePropagation())}})):void 0===Q.get(e,i)&&k.event.add(e,i,ke)}k.event={global:{},add:function(t,e,n,r,i){var o,a,s,u,l,c,f,p,d,h,g,v=Q.get(t);if(v){n.handler&&(n=(o=n).handler,i=o.selector),i&&k.find.matchesSelector(ie,i),n.guid||(n.guid=k.guid++),(u=v.events)||(u=v.events={}),(a=v.handle)||(a=v.handle=function(e){return"undefined"!=typeof k&&k.event.triggered!==e.type?k.event.dispatch.apply(t,arguments):void 0}),l=(e=(e||"").match(R)||[""]).length;while(l--)d=g=(s=Ee.exec(e[l])||[])[1],h=(s[2]||"").split(".").sort(),d&&(f=k.event.special[d]||{},d=(i?f.delegateType:f.bindType)||d,f=k.event.special[d]||{},c=k.extend({type:d,origType:g,data:r,handler:n,guid:n.guid,selector:i,needsContext:i&&k.expr.match.needsContext.test(i),namespace:h.join(".")},o),(p=u[d])||((p=u[d]=[]).delegateCount=0,f.setup&&!1!==f.setup.call(t,r,h,a)||t.addEventListener&&t.addEventListener(d,a)),f.add&&(f.add.call(t,c),c.handler.guid||(c.handler.guid=n.guid)),i?p.splice(p.delegateCount++,0,c):p.push(c),k.event.global[d]=!0)}},remove:function(e,t,n,r,i){var o,a,s,u,l,c,f,p,d,h,g,v=Q.hasData(e)&&Q.get(e);if(v&&(u=v.events)){l=(t=(t||"").match(R)||[""]).length;while(l--)if(d=g=(s=Ee.exec(t[l])||[])[1],h=(s[2]||"").split(".").sort(),d){f=k.event.special[d]||{},p=u[d=(r?f.delegateType:f.bindType)||d]||[],s=s[2]&&new RegExp("(^|\\.)"+h.join("\\.(?:.*\\.|)")+"(\\.|$)"),a=o=p.length;while(o--)c=p[o],!i&&g!==c.origType||n&&n.guid!==c.guid||s&&!s.test(c.namespace)||r&&r!==c.selector&&("**"!==r||!c.selector)||(p.splice(o,1),c.selector&&p.delegateCount--,f.remove&&f.remove.call(e,c));a&&!p.length&&(f.teardown&&!1!==f.teardown.call(e,h,v.handle)||k.removeEvent(e,d,v.handle),delete u[d])}else for(d in u)k.event.remove(e,d+t[l],n,r,!0);k.isEmptyObject(u)&&Q.remove(e,"handle events")}},dispatch:function(e){var t,n,r,i,o,a,s=k.event.fix(e),u=new Array(arguments.length),l=(Q.get(this,"events")||{})[s.type]||[],c=k.event.special[s.type]||{};for(u[0]=s,t=1;t\x20\t\r\n\f]*)[^>]*)\/>/gi,qe=/\s*$/g;function Oe(e,t){return A(e,"table")&&A(11!==t.nodeType?t:t.firstChild,"tr")&&k(e).children("tbody")[0]||e}function Pe(e){return e.type=(null!==e.getAttribute("type"))+"/"+e.type,e}function Re(e){return"true/"===(e.type||"").slice(0,5)?e.type=e.type.slice(5):e.removeAttribute("type"),e}function Me(e,t){var n,r,i,o,a,s,u,l;if(1===t.nodeType){if(Q.hasData(e)&&(o=Q.access(e),a=Q.set(t,o),l=o.events))for(i in delete a.handle,a.events={},l)for(n=0,r=l[i].length;n")},clone:function(e,t,n){var r,i,o,a,s,u,l,c=e.cloneNode(!0),f=oe(e);if(!(y.noCloneChecked||1!==e.nodeType&&11!==e.nodeType||k.isXMLDoc(e)))for(a=ve(c),r=0,i=(o=ve(e)).length;r").attr(n.scriptAttrs||{}).prop({charset:n.scriptCharset,src:n.url}).on("load error",i=function(e){r.remove(),i=null,e&&t("error"===e.type?404:200,e.type)}),E.head.appendChild(r[0])},abort:function(){i&&i()}}});var Vt,Gt=[],Yt=/(=)\?(?=&|$)|\?\?/;k.ajaxSetup({jsonp:"callback",jsonpCallback:function(){var e=Gt.pop()||k.expando+"_"+kt++;return this[e]=!0,e}}),k.ajaxPrefilter("json jsonp",function(e,t,n){var r,i,o,a=!1!==e.jsonp&&(Yt.test(e.url)?"url":"string"==typeof e.data&&0===(e.contentType||"").indexOf("application/x-www-form-urlencoded")&&Yt.test(e.data)&&"data");if(a||"jsonp"===e.dataTypes[0])return r=e.jsonpCallback=m(e.jsonpCallback)?e.jsonpCallback():e.jsonpCallback,a?e[a]=e[a].replace(Yt,"$1"+r):!1!==e.jsonp&&(e.url+=(St.test(e.url)?"&":"?")+e.jsonp+"="+r),e.converters["script json"]=function(){return o||k.error(r+" was not called"),o[0]},e.dataTypes[0]="json",i=C[r],C[r]=function(){o=arguments},n.always(function(){void 0===i?k(C).removeProp(r):C[r]=i,e[r]&&(e.jsonpCallback=t.jsonpCallback,Gt.push(r)),o&&m(i)&&i(o[0]),o=i=void 0}),"script"}),y.createHTMLDocument=((Vt=E.implementation.createHTMLDocument("").body).innerHTML="",2===Vt.childNodes.length),k.parseHTML=function(e,t,n){return"string"!=typeof e?[]:("boolean"==typeof t&&(n=t,t=!1),t||(y.createHTMLDocument?((r=(t=E.implementation.createHTMLDocument("")).createElement("base")).href=E.location.href,t.head.appendChild(r)):t=E),o=!n&&[],(i=D.exec(e))?[t.createElement(i[1])]:(i=we([e],t,o),o&&o.length&&k(o).remove(),k.merge([],i.childNodes)));var r,i,o},k.fn.load=function(e,t,n){var r,i,o,a=this,s=e.indexOf(" ");return-1").append(k.parseHTML(e)).find(r):e)}).always(n&&function(e,t){a.each(function(){n.apply(this,o||[e.responseText,t,e])})}),this},k.each(["ajaxStart","ajaxStop","ajaxComplete","ajaxError","ajaxSuccess","ajaxSend"],function(e,t){k.fn[t]=function(e){return this.on(t,e)}}),k.expr.pseudos.animated=function(t){return k.grep(k.timers,function(e){return t===e.elem}).length},k.offset={setOffset:function(e,t,n){var r,i,o,a,s,u,l=k.css(e,"position"),c=k(e),f={};"static"===l&&(e.style.position="relative"),s=c.offset(),o=k.css(e,"top"),u=k.css(e,"left"),("absolute"===l||"fixed"===l)&&-1<(o+u).indexOf("auto")?(a=(r=c.position()).top,i=r.left):(a=parseFloat(o)||0,i=parseFloat(u)||0),m(t)&&(t=t.call(e,n,k.extend({},s))),null!=t.top&&(f.top=t.top-s.top+a),null!=t.left&&(f.left=t.left-s.left+i),"using"in t?t.using.call(e,f):c.css(f)}},k.fn.extend({offset:function(t){if(arguments.length)return void 0===t?this:this.each(function(e){k.offset.setOffset(this,t,e)});var e,n,r=this[0];return r?r.getClientRects().length?(e=r.getBoundingClientRect(),n=r.ownerDocument.defaultView,{top:e.top+n.pageYOffset,left:e.left+n.pageXOffset}):{top:0,left:0}:void 0},position:function(){if(this[0]){var e,t,n,r=this[0],i={top:0,left:0};if("fixed"===k.css(r,"position"))t=r.getBoundingClientRect();else{t=this.offset(),n=r.ownerDocument,e=r.offsetParent||n.documentElement;while(e&&(e===n.body||e===n.documentElement)&&"static"===k.css(e,"position"))e=e.parentNode;e&&e!==r&&1===e.nodeType&&((i=k(e).offset()).top+=k.css(e,"borderTopWidth",!0),i.left+=k.css(e,"borderLeftWidth",!0))}return{top:t.top-i.top-k.css(r,"marginTop",!0),left:t.left-i.left-k.css(r,"marginLeft",!0)}}},offsetParent:function(){return this.map(function(){var e=this.offsetParent;while(e&&"static"===k.css(e,"position"))e=e.offsetParent;return e||ie})}}),k.each({scrollLeft:"pageXOffset",scrollTop:"pageYOffset"},function(t,i){var o="pageYOffset"===i;k.fn[t]=function(e){return _(this,function(e,t,n){var r;if(x(e)?r=e:9===e.nodeType&&(r=e.defaultView),void 0===n)return r?r[i]:e[t];r?r.scrollTo(o?r.pageXOffset:n,o?n:r.pageYOffset):e[t]=n},t,e,arguments.length)}}),k.each(["top","left"],function(e,n){k.cssHooks[n]=ze(y.pixelPosition,function(e,t){if(t)return t=_e(e,n),$e.test(t)?k(e).position()[n]+"px":t})}),k.each({Height:"height",Width:"width"},function(a,s){k.each({padding:"inner"+a,content:s,"":"outer"+a},function(r,o){k.fn[o]=function(e,t){var n=arguments.length&&(r||"boolean"!=typeof e),i=r||(!0===e||!0===t?"margin":"border");return _(this,function(e,t,n){var r;return x(e)?0===o.indexOf("outer")?e["inner"+a]:e.document.documentElement["client"+a]:9===e.nodeType?(r=e.documentElement,Math.max(e.body["scroll"+a],r["scroll"+a],e.body["offset"+a],r["offset"+a],r["client"+a])):void 0===n?k.css(e,t,i):k.style(e,t,n,i)},s,n?e:void 0,n)}})}),k.each("blur focus focusin focusout resize scroll click dblclick mousedown mouseup mousemove mouseover mouseout mouseenter mouseleave change select submit keydown keypress keyup contextmenu".split(" "),function(e,n){k.fn[n]=function(e,t){return 00 + var meq1 = "^(" + C + ")?" + V + C + "(" + V + ")?$"; // [C]VC[V] is m=1 + var mgr1 = "^(" + C + ")?" + V + C + V + C; // [C]VCVC... is m>1 + var s_v = "^(" + C + ")?" + v; // vowel in stem + + this.stemWord = function (w) { + var stem; + var suffix; + var firstch; + var origword = w; + + if (w.length < 3) + return w; + + var re; + var re2; + var re3; + var re4; + + firstch = w.substr(0,1); + if (firstch == "y") + w = firstch.toUpperCase() + w.substr(1); + + // Step 1a + re = /^(.+?)(ss|i)es$/; + re2 = /^(.+?)([^s])s$/; + + if (re.test(w)) + w = w.replace(re,"$1$2"); + else if (re2.test(w)) + w = w.replace(re2,"$1$2"); + + // Step 1b + re = /^(.+?)eed$/; + re2 = /^(.+?)(ed|ing)$/; + if (re.test(w)) { + var fp = re.exec(w); + re = new RegExp(mgr0); + if (re.test(fp[1])) { + re = /.$/; + w = w.replace(re,""); + } + } + else if (re2.test(w)) { + var fp = re2.exec(w); + stem = fp[1]; + re2 = new RegExp(s_v); + if (re2.test(stem)) { + w = stem; + re2 = /(at|bl|iz)$/; + re3 = new RegExp("([^aeiouylsz])\\1$"); + re4 = new RegExp("^" + C + v + "[^aeiouwxy]$"); + if (re2.test(w)) + w = w + "e"; + else if (re3.test(w)) { + re = /.$/; + w = w.replace(re,""); + } + else if (re4.test(w)) + w = w + "e"; + } + } + + // Step 1c + re = /^(.+?)y$/; + if (re.test(w)) { + var fp = re.exec(w); + stem = fp[1]; + re = new RegExp(s_v); + if (re.test(stem)) + w = stem + "i"; + } + + // Step 2 + re = /^(.+?)(ational|tional|enci|anci|izer|bli|alli|entli|eli|ousli|ization|ation|ator|alism|iveness|fulness|ousness|aliti|iviti|biliti|logi)$/; + if (re.test(w)) { + var fp = re.exec(w); + stem = fp[1]; + suffix = fp[2]; + re = new RegExp(mgr0); + if (re.test(stem)) + w = stem + step2list[suffix]; + } + + // Step 3 + re = /^(.+?)(icate|ative|alize|iciti|ical|ful|ness)$/; + if (re.test(w)) { + var fp = re.exec(w); + stem = fp[1]; + suffix = fp[2]; + re = new RegExp(mgr0); + if (re.test(stem)) + w = stem + step3list[suffix]; + } + + // Step 4 + re = /^(.+?)(al|ance|ence|er|ic|able|ible|ant|ement|ment|ent|ou|ism|ate|iti|ous|ive|ize)$/; + re2 = /^(.+?)(s|t)(ion)$/; + if (re.test(w)) { + var fp = re.exec(w); + stem = fp[1]; + re = new RegExp(mgr1); + if (re.test(stem)) + w = stem; + } + else if (re2.test(w)) { + var fp = re2.exec(w); + stem = fp[1] + fp[2]; + re2 = new RegExp(mgr1); + if (re2.test(stem)) + w = stem; + } + + // Step 5 + re = /^(.+?)e$/; + if (re.test(w)) { + var fp = re.exec(w); + stem = fp[1]; + re = new RegExp(mgr1); + re2 = new RegExp(meq1); + re3 = new RegExp("^" + C + v + "[^aeiouwxy]$"); + if (re.test(stem) || (re2.test(stem) && !(re3.test(stem)))) + w = stem; + } + re = /ll$/; + re2 = new RegExp(mgr1); + if (re.test(w) && re2.test(w)) { + re = /.$/; + w = w.replace(re,""); + } + + // and turn initial Y back to y + if (firstch == "y") + w = firstch.toLowerCase() + w.substr(1); + return w; + } +} + + + + + +var splitChars = (function() { + var result = {}; + var singles = [96, 180, 187, 191, 215, 247, 749, 885, 903, 907, 909, 930, 1014, 1648, + 1748, 1809, 2416, 2473, 2481, 2526, 2601, 2609, 2612, 2615, 2653, 2702, + 2706, 2729, 2737, 2740, 2857, 2865, 2868, 2910, 2928, 2948, 2961, 2971, + 2973, 3085, 3089, 3113, 3124, 3213, 3217, 3241, 3252, 3295, 3341, 3345, + 3369, 3506, 3516, 3633, 3715, 3721, 3736, 3744, 3748, 3750, 3756, 3761, + 3781, 3912, 4239, 4347, 4681, 4695, 4697, 4745, 4785, 4799, 4801, 4823, + 4881, 5760, 5901, 5997, 6313, 7405, 8024, 8026, 8028, 8030, 8117, 8125, + 8133, 8181, 8468, 8485, 8487, 8489, 8494, 8527, 11311, 11359, 11687, 11695, + 11703, 11711, 11719, 11727, 11735, 12448, 12539, 43010, 43014, 43019, 43587, + 43696, 43713, 64286, 64297, 64311, 64317, 64319, 64322, 64325, 65141]; + var i, j, start, end; + for (i = 0; i < singles.length; i++) { + result[singles[i]] = true; + } + var ranges = [[0, 47], [58, 64], [91, 94], [123, 169], [171, 177], [182, 184], [706, 709], + [722, 735], [741, 747], [751, 879], [888, 889], [894, 901], [1154, 1161], + [1318, 1328], [1367, 1368], [1370, 1376], [1416, 1487], [1515, 1519], [1523, 1568], + [1611, 1631], [1642, 1645], [1750, 1764], [1767, 1773], [1789, 1790], [1792, 1807], + [1840, 1868], [1958, 1968], [1970, 1983], [2027, 2035], [2038, 2041], [2043, 2047], + [2070, 2073], [2075, 2083], [2085, 2087], [2089, 2307], [2362, 2364], [2366, 2383], + [2385, 2391], [2402, 2405], [2419, 2424], [2432, 2436], [2445, 2446], [2449, 2450], + [2483, 2485], [2490, 2492], [2494, 2509], [2511, 2523], [2530, 2533], [2546, 2547], + [2554, 2564], [2571, 2574], [2577, 2578], [2618, 2648], [2655, 2661], [2672, 2673], + [2677, 2692], [2746, 2748], [2750, 2767], [2769, 2783], [2786, 2789], [2800, 2820], + [2829, 2830], [2833, 2834], [2874, 2876], [2878, 2907], [2914, 2917], [2930, 2946], + [2955, 2957], [2966, 2968], [2976, 2978], [2981, 2983], [2987, 2989], [3002, 3023], + [3025, 3045], [3059, 3076], [3130, 3132], [3134, 3159], [3162, 3167], [3170, 3173], + [3184, 3191], [3199, 3204], [3258, 3260], [3262, 3293], [3298, 3301], [3312, 3332], + [3386, 3388], [3390, 3423], [3426, 3429], [3446, 3449], [3456, 3460], [3479, 3481], + [3518, 3519], [3527, 3584], [3636, 3647], [3655, 3663], [3674, 3712], [3717, 3718], + [3723, 3724], [3726, 3731], [3752, 3753], [3764, 3772], [3774, 3775], [3783, 3791], + [3802, 3803], [3806, 3839], [3841, 3871], [3892, 3903], [3949, 3975], [3980, 4095], + [4139, 4158], [4170, 4175], [4182, 4185], [4190, 4192], [4194, 4196], [4199, 4205], + [4209, 4212], [4226, 4237], [4250, 4255], [4294, 4303], [4349, 4351], [4686, 4687], + [4702, 4703], [4750, 4751], [4790, 4791], [4806, 4807], [4886, 4887], [4955, 4968], + [4989, 4991], [5008, 5023], [5109, 5120], [5741, 5742], [5787, 5791], [5867, 5869], + [5873, 5887], [5906, 5919], [5938, 5951], [5970, 5983], [6001, 6015], [6068, 6102], + [6104, 6107], [6109, 6111], [6122, 6127], [6138, 6159], [6170, 6175], [6264, 6271], + [6315, 6319], [6390, 6399], [6429, 6469], [6510, 6511], [6517, 6527], [6572, 6592], + [6600, 6607], [6619, 6655], [6679, 6687], [6741, 6783], [6794, 6799], [6810, 6822], + [6824, 6916], [6964, 6980], [6988, 6991], [7002, 7042], [7073, 7085], [7098, 7167], + [7204, 7231], [7242, 7244], [7294, 7400], [7410, 7423], [7616, 7679], [7958, 7959], + [7966, 7967], [8006, 8007], [8014, 8015], [8062, 8063], [8127, 8129], [8141, 8143], + [8148, 8149], [8156, 8159], [8173, 8177], [8189, 8303], [8306, 8307], [8314, 8318], + [8330, 8335], [8341, 8449], [8451, 8454], [8456, 8457], [8470, 8472], [8478, 8483], + [8506, 8507], [8512, 8516], [8522, 8525], [8586, 9311], [9372, 9449], [9472, 10101], + [10132, 11263], [11493, 11498], [11503, 11516], [11518, 11519], [11558, 11567], + [11622, 11630], [11632, 11647], [11671, 11679], [11743, 11822], [11824, 12292], + [12296, 12320], [12330, 12336], [12342, 12343], [12349, 12352], [12439, 12444], + [12544, 12548], [12590, 12592], [12687, 12689], [12694, 12703], [12728, 12783], + [12800, 12831], [12842, 12880], [12896, 12927], [12938, 12976], [12992, 13311], + [19894, 19967], [40908, 40959], [42125, 42191], [42238, 42239], [42509, 42511], + [42540, 42559], [42592, 42593], [42607, 42622], [42648, 42655], [42736, 42774], + [42784, 42785], [42889, 42890], [42893, 43002], [43043, 43055], [43062, 43071], + [43124, 43137], [43188, 43215], [43226, 43249], [43256, 43258], [43260, 43263], + [43302, 43311], [43335, 43359], [43389, 43395], [43443, 43470], [43482, 43519], + [43561, 43583], [43596, 43599], [43610, 43615], [43639, 43641], [43643, 43647], + [43698, 43700], [43703, 43704], [43710, 43711], [43715, 43738], [43742, 43967], + [44003, 44015], [44026, 44031], [55204, 55215], [55239, 55242], [55292, 55295], + [57344, 63743], [64046, 64047], [64110, 64111], [64218, 64255], [64263, 64274], + [64280, 64284], [64434, 64466], [64830, 64847], [64912, 64913], [64968, 65007], + [65020, 65135], [65277, 65295], [65306, 65312], [65339, 65344], [65371, 65381], + [65471, 65473], [65480, 65481], [65488, 65489], [65496, 65497]]; + for (i = 0; i < ranges.length; i++) { + start = ranges[i][0]; + end = ranges[i][1]; + for (j = start; j <= end; j++) { + result[j] = true; + } + } + return result; +})(); + +function splitQuery(query) { + var result = []; + var start = -1; + for (var i = 0; i < query.length; i++) { + if (splitChars[query.charCodeAt(i)]) { + if (start !== -1) { + result.push(query.slice(start, i)); + start = -1; + } + } else if (start === -1) { + start = i; + } + } + if (start !== -1) { + result.push(query.slice(start)); + } + return result; +} + + diff --git a/docs/en/1.1b2/_static/js/materialize.min.js b/docs/en/1.1b2/_static/js/materialize.min.js new file mode 100644 index 0000000..7d80c93 --- /dev/null +++ b/docs/en/1.1b2/_static/js/materialize.min.js @@ -0,0 +1,6 @@ +/*! + * Materialize v1.0.0 (http://materializecss.com) + * Copyright 2014-2017 Materialize + * MIT License (https://raw.githubusercontent.com/Dogfalo/materialize/master/LICENSE) + */ +var _get=function t(e,i,n){null===e&&(e=Function.prototype);var s=Object.getOwnPropertyDescriptor(e,i);if(void 0===s){var o=Object.getPrototypeOf(e);return null===o?void 0:t(o,i,n)}if("value"in s)return s.value;var a=s.get;return void 0!==a?a.call(n):void 0},_createClass=function(){function n(t,e){for(var i=0;i/,p=/^\w+$/;function v(t,e){e=e||o;var i=u.test(t)?e.getElementsByClassName(t.slice(1)):p.test(t)?e.getElementsByTagName(t):e.querySelectorAll(t);return i}function f(t){if(!i){var e=(i=o.implementation.createHTMLDocument(null)).createElement("base");e.href=o.location.href,i.head.appendChild(e)}return i.body.innerHTML=t,i.body.childNodes}function m(t){"loading"!==o.readyState?t():o.addEventListener("DOMContentLoaded",t)}function g(t,e){if(!t)return this;if(t.cash&&t!==a)return t;var i,n=t,s=0;if(d(t))n=l.test(t)?o.getElementById(t.slice(1)):c.test(t)?f(t):v(t,e);else if(h(t))return m(t),this;if(!n)return this;if(n.nodeType||n===a)this[0]=n,this.length=1;else for(i=this.length=n.length;ss.right-i||l+e.width>window.innerWidth-i)&&(n.right=!0),(ho-i||h+e.height>window.innerHeight-i)&&(n.bottom=!0),n},M.checkPossibleAlignments=function(t,e,i,n){var s={top:!0,right:!0,bottom:!0,left:!0,spaceOnTop:null,spaceOnRight:null,spaceOnBottom:null,spaceOnLeft:null},o="visible"===getComputedStyle(e).overflow,a=e.getBoundingClientRect(),r=Math.min(a.height,window.innerHeight),l=Math.min(a.width,window.innerWidth),h=t.getBoundingClientRect(),d=e.scrollLeft,u=e.scrollTop,c=i.left-d,p=i.top-u,v=i.top+h.height-u;return s.spaceOnRight=o?window.innerWidth-(h.left+i.width):l-(c+i.width),s.spaceOnRight<0&&(s.left=!1),s.spaceOnLeft=o?h.right-i.width:c-i.width+h.width,s.spaceOnLeft<0&&(s.right=!1),s.spaceOnBottom=o?window.innerHeight-(h.top+i.height+n):r-(p+i.height+n),s.spaceOnBottom<0&&(s.top=!1),s.spaceOnTop=o?h.bottom-(i.height+n):v-(i.height-n),s.spaceOnTop<0&&(s.bottom=!1),s},M.getOverflowParent=function(t){return null==t?null:t===document.body||"visible"!==getComputedStyle(t).overflow?t:M.getOverflowParent(t.parentElement)},M.getIdFromTrigger=function(t){var e=t.getAttribute("data-target");return e||(e=(e=t.getAttribute("href"))?e.slice(1):""),e},M.getDocumentScrollTop=function(){return window.pageYOffset||document.documentElement.scrollTop||document.body.scrollTop||0},M.getDocumentScrollLeft=function(){return window.pageXOffset||document.documentElement.scrollLeft||document.body.scrollLeft||0};var getTime=Date.now||function(){return(new Date).getTime()};M.throttle=function(i,n,s){var o=void 0,a=void 0,r=void 0,l=null,h=0;s||(s={});var d=function(){h=!1===s.leading?0:getTime(),l=null,r=i.apply(o,a),o=a=null};return function(){var t=getTime();h||!1!==s.leading||(h=t);var e=n-(t-h);return o=this,a=arguments,e<=0?(clearTimeout(l),l=null,h=t,r=i.apply(o,a),o=a=null):l||!1===s.trailing||(l=setTimeout(d,e)),r}};var $jscomp={scope:{}};$jscomp.defineProperty="function"==typeof Object.defineProperties?Object.defineProperty:function(t,e,i){if(i.get||i.set)throw new TypeError("ES3 does not support getters and setters.");t!=Array.prototype&&t!=Object.prototype&&(t[e]=i.value)},$jscomp.getGlobal=function(t){return"undefined"!=typeof window&&window===t?t:"undefined"!=typeof global&&null!=global?global:t},$jscomp.global=$jscomp.getGlobal(this),$jscomp.SYMBOL_PREFIX="jscomp_symbol_",$jscomp.initSymbol=function(){$jscomp.initSymbol=function(){},$jscomp.global.Symbol||($jscomp.global.Symbol=$jscomp.Symbol)},$jscomp.symbolCounter_=0,$jscomp.Symbol=function(t){return $jscomp.SYMBOL_PREFIX+(t||"")+$jscomp.symbolCounter_++},$jscomp.initSymbolIterator=function(){$jscomp.initSymbol();var t=$jscomp.global.Symbol.iterator;t||(t=$jscomp.global.Symbol.iterator=$jscomp.global.Symbol("iterator")),"function"!=typeof Array.prototype[t]&&$jscomp.defineProperty(Array.prototype,t,{configurable:!0,writable:!0,value:function(){return $jscomp.arrayIterator(this)}}),$jscomp.initSymbolIterator=function(){}},$jscomp.arrayIterator=function(t){var e=0;return $jscomp.iteratorPrototype(function(){return e=k.currentTime)for(var h=0;ht&&(s.duration=e.duration),s.children.push(e)}),s.seek(0),s.reset(),s.autoplay&&s.restart(),s},s},O.random=function(t,e){return Math.floor(Math.random()*(e-t+1))+t},O}(),function(r,l){"use strict";var e={accordion:!0,onOpenStart:void 0,onOpenEnd:void 0,onCloseStart:void 0,onCloseEnd:void 0,inDuration:300,outDuration:300},t=function(t){function s(t,e){_classCallCheck(this,s);var i=_possibleConstructorReturn(this,(s.__proto__||Object.getPrototypeOf(s)).call(this,s,t,e));(i.el.M_Collapsible=i).options=r.extend({},s.defaults,e),i.$headers=i.$el.children("li").children(".collapsible-header"),i.$headers.attr("tabindex",0),i._setupEventHandlers();var n=i.$el.children("li.active").children(".collapsible-body");return i.options.accordion?n.first().css("display","block"):n.css("display","block"),i}return _inherits(s,Component),_createClass(s,[{key:"destroy",value:function(){this._removeEventHandlers(),this.el.M_Collapsible=void 0}},{key:"_setupEventHandlers",value:function(){var e=this;this._handleCollapsibleClickBound=this._handleCollapsibleClick.bind(this),this._handleCollapsibleKeydownBound=this._handleCollapsibleKeydown.bind(this),this.el.addEventListener("click",this._handleCollapsibleClickBound),this.$headers.each(function(t){t.addEventListener("keydown",e._handleCollapsibleKeydownBound)})}},{key:"_removeEventHandlers",value:function(){var e=this;this.el.removeEventListener("click",this._handleCollapsibleClickBound),this.$headers.each(function(t){t.removeEventListener("keydown",e._handleCollapsibleKeydownBound)})}},{key:"_handleCollapsibleClick",value:function(t){var e=r(t.target).closest(".collapsible-header");if(t.target&&e.length){var i=e.closest(".collapsible");if(i[0]===this.el){var n=e.closest("li"),s=i.children("li"),o=n[0].classList.contains("active"),a=s.index(n);o?this.close(a):this.open(a)}}}},{key:"_handleCollapsibleKeydown",value:function(t){13===t.keyCode&&this._handleCollapsibleClickBound(t)}},{key:"_animateIn",value:function(t){var e=this,i=this.$el.children("li").eq(t);if(i.length){var n=i.children(".collapsible-body");l.remove(n[0]),n.css({display:"block",overflow:"hidden",height:0,paddingTop:"",paddingBottom:""});var s=n.css("padding-top"),o=n.css("padding-bottom"),a=n[0].scrollHeight;n.css({paddingTop:0,paddingBottom:0}),l({targets:n[0],height:a,paddingTop:s,paddingBottom:o,duration:this.options.inDuration,easing:"easeInOutCubic",complete:function(t){n.css({overflow:"",paddingTop:"",paddingBottom:"",height:""}),"function"==typeof e.options.onOpenEnd&&e.options.onOpenEnd.call(e,i[0])}})}}},{key:"_animateOut",value:function(t){var e=this,i=this.$el.children("li").eq(t);if(i.length){var n=i.children(".collapsible-body");l.remove(n[0]),n.css("overflow","hidden"),l({targets:n[0],height:0,paddingTop:0,paddingBottom:0,duration:this.options.outDuration,easing:"easeInOutCubic",complete:function(){n.css({height:"",overflow:"",padding:"",display:""}),"function"==typeof e.options.onCloseEnd&&e.options.onCloseEnd.call(e,i[0])}})}}},{key:"open",value:function(t){var i=this,e=this.$el.children("li").eq(t);if(e.length&&!e[0].classList.contains("active")){if("function"==typeof this.options.onOpenStart&&this.options.onOpenStart.call(this,e[0]),this.options.accordion){var n=this.$el.children("li");this.$el.children("li.active").each(function(t){var e=n.index(r(t));i.close(e)})}e[0].classList.add("active"),this._animateIn(t)}}},{key:"close",value:function(t){var e=this.$el.children("li").eq(t);e.length&&e[0].classList.contains("active")&&("function"==typeof this.options.onCloseStart&&this.options.onCloseStart.call(this,e[0]),e[0].classList.remove("active"),this._animateOut(t))}}],[{key:"init",value:function(t,e){return _get(s.__proto__||Object.getPrototypeOf(s),"init",this).call(this,this,t,e)}},{key:"getInstance",value:function(t){return(t.jquery?t[0]:t).M_Collapsible}},{key:"defaults",get:function(){return e}}]),s}();M.Collapsible=t,M.jQueryLoaded&&M.initializeJqueryWrapper(t,"collapsible","M_Collapsible")}(cash,M.anime),function(h,i){"use strict";var e={alignment:"left",autoFocus:!0,constrainWidth:!0,container:null,coverTrigger:!0,closeOnClick:!0,hover:!1,inDuration:150,outDuration:250,onOpenStart:null,onOpenEnd:null,onCloseStart:null,onCloseEnd:null,onItemClick:null},t=function(t){function n(t,e){_classCallCheck(this,n);var i=_possibleConstructorReturn(this,(n.__proto__||Object.getPrototypeOf(n)).call(this,n,t,e));return i.el.M_Dropdown=i,n._dropdowns.push(i),i.id=M.getIdFromTrigger(t),i.dropdownEl=document.getElementById(i.id),i.$dropdownEl=h(i.dropdownEl),i.options=h.extend({},n.defaults,e),i.isOpen=!1,i.isScrollable=!1,i.isTouchMoving=!1,i.focusedIndex=-1,i.filterQuery=[],i.options.container?h(i.options.container).append(i.dropdownEl):i.$el.after(i.dropdownEl),i._makeDropdownFocusable(),i._resetFilterQueryBound=i._resetFilterQuery.bind(i),i._handleDocumentClickBound=i._handleDocumentClick.bind(i),i._handleDocumentTouchmoveBound=i._handleDocumentTouchmove.bind(i),i._handleDropdownClickBound=i._handleDropdownClick.bind(i),i._handleDropdownKeydownBound=i._handleDropdownKeydown.bind(i),i._handleTriggerKeydownBound=i._handleTriggerKeydown.bind(i),i._setupEventHandlers(),i}return _inherits(n,Component),_createClass(n,[{key:"destroy",value:function(){this._resetDropdownStyles(),this._removeEventHandlers(),n._dropdowns.splice(n._dropdowns.indexOf(this),1),this.el.M_Dropdown=void 0}},{key:"_setupEventHandlers",value:function(){this.el.addEventListener("keydown",this._handleTriggerKeydownBound),this.dropdownEl.addEventListener("click",this._handleDropdownClickBound),this.options.hover?(this._handleMouseEnterBound=this._handleMouseEnter.bind(this),this.el.addEventListener("mouseenter",this._handleMouseEnterBound),this._handleMouseLeaveBound=this._handleMouseLeave.bind(this),this.el.addEventListener("mouseleave",this._handleMouseLeaveBound),this.dropdownEl.addEventListener("mouseleave",this._handleMouseLeaveBound)):(this._handleClickBound=this._handleClick.bind(this),this.el.addEventListener("click",this._handleClickBound))}},{key:"_removeEventHandlers",value:function(){this.el.removeEventListener("keydown",this._handleTriggerKeydownBound),this.dropdownEl.removeEventListener("click",this._handleDropdownClickBound),this.options.hover?(this.el.removeEventListener("mouseenter",this._handleMouseEnterBound),this.el.removeEventListener("mouseleave",this._handleMouseLeaveBound),this.dropdownEl.removeEventListener("mouseleave",this._handleMouseLeaveBound)):this.el.removeEventListener("click",this._handleClickBound)}},{key:"_setupTemporaryEventHandlers",value:function(){document.body.addEventListener("click",this._handleDocumentClickBound,!0),document.body.addEventListener("touchend",this._handleDocumentClickBound),document.body.addEventListener("touchmove",this._handleDocumentTouchmoveBound),this.dropdownEl.addEventListener("keydown",this._handleDropdownKeydownBound)}},{key:"_removeTemporaryEventHandlers",value:function(){document.body.removeEventListener("click",this._handleDocumentClickBound,!0),document.body.removeEventListener("touchend",this._handleDocumentClickBound),document.body.removeEventListener("touchmove",this._handleDocumentTouchmoveBound),this.dropdownEl.removeEventListener("keydown",this._handleDropdownKeydownBound)}},{key:"_handleClick",value:function(t){t.preventDefault(),this.open()}},{key:"_handleMouseEnter",value:function(){this.open()}},{key:"_handleMouseLeave",value:function(t){var e=t.toElement||t.relatedTarget,i=!!h(e).closest(".dropdown-content").length,n=!1,s=h(e).closest(".dropdown-trigger");s.length&&s[0].M_Dropdown&&s[0].M_Dropdown.isOpen&&(n=!0),n||i||this.close()}},{key:"_handleDocumentClick",value:function(t){var e=this,i=h(t.target);this.options.closeOnClick&&i.closest(".dropdown-content").length&&!this.isTouchMoving?setTimeout(function(){e.close()},0):!i.closest(".dropdown-trigger").length&&i.closest(".dropdown-content").length||setTimeout(function(){e.close()},0),this.isTouchMoving=!1}},{key:"_handleTriggerKeydown",value:function(t){t.which!==M.keys.ARROW_DOWN&&t.which!==M.keys.ENTER||this.isOpen||(t.preventDefault(),this.open())}},{key:"_handleDocumentTouchmove",value:function(t){h(t.target).closest(".dropdown-content").length&&(this.isTouchMoving=!0)}},{key:"_handleDropdownClick",value:function(t){if("function"==typeof this.options.onItemClick){var e=h(t.target).closest("li")[0];this.options.onItemClick.call(this,e)}}},{key:"_handleDropdownKeydown",value:function(t){if(t.which===M.keys.TAB)t.preventDefault(),this.close();else if(t.which!==M.keys.ARROW_DOWN&&t.which!==M.keys.ARROW_UP||!this.isOpen)if(t.which===M.keys.ENTER&&this.isOpen){var e=this.dropdownEl.children[this.focusedIndex],i=h(e).find("a, button").first();i.length?i[0].click():e&&e.click()}else t.which===M.keys.ESC&&this.isOpen&&(t.preventDefault(),this.close());else{t.preventDefault();var n=t.which===M.keys.ARROW_DOWN?1:-1,s=this.focusedIndex,o=!1;do{if(s+=n,this.dropdownEl.children[s]&&-1!==this.dropdownEl.children[s].tabIndex){o=!0;break}}while(sl.spaceOnBottom?(h="bottom",i+=l.spaceOnTop,o-=l.spaceOnTop):i+=l.spaceOnBottom)),!l[d]){var u="left"===d?"right":"left";l[u]?d=u:l.spaceOnLeft>l.spaceOnRight?(d="right",n+=l.spaceOnLeft,s-=l.spaceOnLeft):(d="left",n+=l.spaceOnRight)}return"bottom"===h&&(o=o-e.height+(this.options.coverTrigger?t.height:0)),"right"===d&&(s=s-e.width+t.width),{x:s,y:o,verticalAlignment:h,horizontalAlignment:d,height:i,width:n}}},{key:"_animateIn",value:function(){var e=this;i.remove(this.dropdownEl),i({targets:this.dropdownEl,opacity:{value:[0,1],easing:"easeOutQuad"},scaleX:[.3,1],scaleY:[.3,1],duration:this.options.inDuration,easing:"easeOutQuint",complete:function(t){e.options.autoFocus&&e.dropdownEl.focus(),"function"==typeof e.options.onOpenEnd&&e.options.onOpenEnd.call(e,e.el)}})}},{key:"_animateOut",value:function(){var e=this;i.remove(this.dropdownEl),i({targets:this.dropdownEl,opacity:{value:0,easing:"easeOutQuint"},scaleX:.3,scaleY:.3,duration:this.options.outDuration,easing:"easeOutQuint",complete:function(t){e._resetDropdownStyles(),"function"==typeof e.options.onCloseEnd&&e.options.onCloseEnd.call(e,e.el)}})}},{key:"_placeDropdown",value:function(){var t=this.options.constrainWidth?this.el.getBoundingClientRect().width:this.dropdownEl.getBoundingClientRect().width;this.dropdownEl.style.width=t+"px";var e=this._getDropdownPosition();this.dropdownEl.style.left=e.x+"px",this.dropdownEl.style.top=e.y+"px",this.dropdownEl.style.height=e.height+"px",this.dropdownEl.style.width=e.width+"px",this.dropdownEl.style.transformOrigin=("left"===e.horizontalAlignment?"0":"100%")+" "+("top"===e.verticalAlignment?"0":"100%")}},{key:"open",value:function(){this.isOpen||(this.isOpen=!0,"function"==typeof this.options.onOpenStart&&this.options.onOpenStart.call(this,this.el),this._resetDropdownStyles(),this.dropdownEl.style.display="block",this._placeDropdown(),this._animateIn(),this._setupTemporaryEventHandlers())}},{key:"close",value:function(){this.isOpen&&(this.isOpen=!1,this.focusedIndex=-1,"function"==typeof this.options.onCloseStart&&this.options.onCloseStart.call(this,this.el),this._animateOut(),this._removeTemporaryEventHandlers(),this.options.autoFocus&&this.el.focus())}},{key:"recalculateDimensions",value:function(){this.isOpen&&(this.$dropdownEl.css({width:"",height:"",left:"",top:"","transform-origin":""}),this._placeDropdown())}}],[{key:"init",value:function(t,e){return _get(n.__proto__||Object.getPrototypeOf(n),"init",this).call(this,this,t,e)}},{key:"getInstance",value:function(t){return(t.jquery?t[0]:t).M_Dropdown}},{key:"defaults",get:function(){return e}}]),n}();t._dropdowns=[],M.Dropdown=t,M.jQueryLoaded&&M.initializeJqueryWrapper(t,"dropdown","M_Dropdown")}(cash,M.anime),function(s,i){"use strict";var e={opacity:.5,inDuration:250,outDuration:250,onOpenStart:null,onOpenEnd:null,onCloseStart:null,onCloseEnd:null,preventScrolling:!0,dismissible:!0,startingTop:"4%",endingTop:"10%"},t=function(t){function n(t,e){_classCallCheck(this,n);var i=_possibleConstructorReturn(this,(n.__proto__||Object.getPrototypeOf(n)).call(this,n,t,e));return(i.el.M_Modal=i).options=s.extend({},n.defaults,e),i.isOpen=!1,i.id=i.$el.attr("id"),i._openingTrigger=void 0,i.$overlay=s(''),i.el.tabIndex=0,i._nthModalOpened=0,n._count++,i._setupEventHandlers(),i}return _inherits(n,Component),_createClass(n,[{key:"destroy",value:function(){n._count--,this._removeEventHandlers(),this.el.removeAttribute("style"),this.$overlay.remove(),this.el.M_Modal=void 0}},{key:"_setupEventHandlers",value:function(){this._handleOverlayClickBound=this._handleOverlayClick.bind(this),this._handleModalCloseClickBound=this._handleModalCloseClick.bind(this),1===n._count&&document.body.addEventListener("click",this._handleTriggerClick),this.$overlay[0].addEventListener("click",this._handleOverlayClickBound),this.el.addEventListener("click",this._handleModalCloseClickBound)}},{key:"_removeEventHandlers",value:function(){0===n._count&&document.body.removeEventListener("click",this._handleTriggerClick),this.$overlay[0].removeEventListener("click",this._handleOverlayClickBound),this.el.removeEventListener("click",this._handleModalCloseClickBound)}},{key:"_handleTriggerClick",value:function(t){var e=s(t.target).closest(".modal-trigger");if(e.length){var i=M.getIdFromTrigger(e[0]),n=document.getElementById(i).M_Modal;n&&n.open(e),t.preventDefault()}}},{key:"_handleOverlayClick",value:function(){this.options.dismissible&&this.close()}},{key:"_handleModalCloseClick",value:function(t){s(t.target).closest(".modal-close").length&&this.close()}},{key:"_handleKeydown",value:function(t){27===t.keyCode&&this.options.dismissible&&this.close()}},{key:"_handleFocus",value:function(t){this.el.contains(t.target)||this._nthModalOpened!==n._modalsOpen||this.el.focus()}},{key:"_animateIn",value:function(){var t=this;s.extend(this.el.style,{display:"block",opacity:0}),s.extend(this.$overlay[0].style,{display:"block",opacity:0}),i({targets:this.$overlay[0],opacity:this.options.opacity,duration:this.options.inDuration,easing:"easeOutQuad"});var e={targets:this.el,duration:this.options.inDuration,easing:"easeOutCubic",complete:function(){"function"==typeof t.options.onOpenEnd&&t.options.onOpenEnd.call(t,t.el,t._openingTrigger)}};this.el.classList.contains("bottom-sheet")?s.extend(e,{bottom:0,opacity:1}):s.extend(e,{top:[this.options.startingTop,this.options.endingTop],opacity:1,scaleX:[.8,1],scaleY:[.8,1]}),i(e)}},{key:"_animateOut",value:function(){var t=this;i({targets:this.$overlay[0],opacity:0,duration:this.options.outDuration,easing:"easeOutQuart"});var e={targets:this.el,duration:this.options.outDuration,easing:"easeOutCubic",complete:function(){t.el.style.display="none",t.$overlay.remove(),"function"==typeof t.options.onCloseEnd&&t.options.onCloseEnd.call(t,t.el)}};this.el.classList.contains("bottom-sheet")?s.extend(e,{bottom:"-100%",opacity:0}):s.extend(e,{top:[this.options.endingTop,this.options.startingTop],opacity:0,scaleX:.8,scaleY:.8}),i(e)}},{key:"open",value:function(t){if(!this.isOpen)return this.isOpen=!0,n._modalsOpen++,this._nthModalOpened=n._modalsOpen,this.$overlay[0].style.zIndex=1e3+2*n._modalsOpen,this.el.style.zIndex=1e3+2*n._modalsOpen+1,this._openingTrigger=t?t[0]:void 0,"function"==typeof this.options.onOpenStart&&this.options.onOpenStart.call(this,this.el,this._openingTrigger),this.options.preventScrolling&&(document.body.style.overflow="hidden"),this.el.classList.add("open"),this.el.insertAdjacentElement("afterend",this.$overlay[0]),this.options.dismissible&&(this._handleKeydownBound=this._handleKeydown.bind(this),this._handleFocusBound=this._handleFocus.bind(this),document.addEventListener("keydown",this._handleKeydownBound),document.addEventListener("focus",this._handleFocusBound,!0)),i.remove(this.el),i.remove(this.$overlay[0]),this._animateIn(),this.el.focus(),this}},{key:"close",value:function(){if(this.isOpen)return this.isOpen=!1,n._modalsOpen--,this._nthModalOpened=0,"function"==typeof this.options.onCloseStart&&this.options.onCloseStart.call(this,this.el),this.el.classList.remove("open"),0===n._modalsOpen&&(document.body.style.overflow=""),this.options.dismissible&&(document.removeEventListener("keydown",this._handleKeydownBound),document.removeEventListener("focus",this._handleFocusBound,!0)),i.remove(this.el),i.remove(this.$overlay[0]),this._animateOut(),this}}],[{key:"init",value:function(t,e){return _get(n.__proto__||Object.getPrototypeOf(n),"init",this).call(this,this,t,e)}},{key:"getInstance",value:function(t){return(t.jquery?t[0]:t).M_Modal}},{key:"defaults",get:function(){return e}}]),n}();t._modalsOpen=0,t._count=0,M.Modal=t,M.jQueryLoaded&&M.initializeJqueryWrapper(t,"modal","M_Modal")}(cash,M.anime),function(o,a){"use strict";var e={inDuration:275,outDuration:200,onOpenStart:null,onOpenEnd:null,onCloseStart:null,onCloseEnd:null},t=function(t){function n(t,e){_classCallCheck(this,n);var i=_possibleConstructorReturn(this,(n.__proto__||Object.getPrototypeOf(n)).call(this,n,t,e));return(i.el.M_Materialbox=i).options=o.extend({},n.defaults,e),i.overlayActive=!1,i.doneAnimating=!0,i.placeholder=o("

'),this.$slides.each(function(t,e){var i=s('

'+this.renderHead(t)+this.renderBody(e)+"

',f=!0,m=!0;for(d=[],l=0;l<12;l++)d.push('");for(a='",g.isArray(u.yearRange)?(l=u.yearRange[0],h=u.yearRange[1]+1):(l=i-u.yearRange,h=1+i+u.yearRange),d=[];l=u.minYear&&d.push('");r='";v+='',v+='

',u.showMonthAfterYear?v+=r+a:v+=a+r,v+="

",c&&(0===n||u.minMonth>=n)&&(f=!1),p&&(11===n||u.maxMonth<=n)&&(m=!1);return(v+='')+"

'),this.$pmBtn=h('

"),r=d("");r.html(o),a.addClass(n+" "+s),a.append(r);var l=e.getAttribute("data-icon");if(l){var h=d('

');a.prepend(h)}return d(this.dropdownOptions).append(a[0]),a[0]}},{key:"_toggleEntryFromArray",value:function(t){var e=!this._keysSelected.hasOwnProperty(t),i=d(this._valueDict[t].optionEl);return e?this._keysSelected[t]=!0:delete this._keysSelected[t],i.toggleClass("selected",e),i.find('input[type="checkbox"]').prop("checked",e),i.prop("selected",e),e}},{key:"_setValueToInput",value:function(){var i=[];if(this.$el.find("option").each(function(t){if(d(t).prop("selected")){var e=d(t).text();i.push(e)}}),!i.length){var t=this.$el.find("option:disabled").eq(0);t.length&&""===t[0].value&&i.push(t.text())}this.input.value=i.join(", ")}},{key:"_setSelectedStates",value:function(){for(var t in this._keysSelected={},this._valueDict){var e=this._valueDict[t],i=d(e.el).prop("selected");d(e.optionEl).find('input[type="checkbox"]').prop("checked",i),i?(this._activateOption(d(this.dropdownOptions),d(e.optionEl)),this._keysSelected[t]=!0):d(e.optionEl).removeClass("selected")}}},{key:"_activateOption",value:function(t,e){e&&(this.isMultiple||t.find("li.selected").removeClass("selected"),d(e).addClass("selected"))}},{key:"getSelectedValues",value:function(){var t=[];for(var e in this._keysSelected)t.push(this._valueDict[e].el.value);return t}}],[{key:"init",value:function(t,e){return _get(n.__proto__||Object.getPrototypeOf(n),"init",this).call(this,this,t,e)}},{key:"getInstance",value:function(t){return(t.jquery?t[0]:t).M_FormSelect}},{key:"defaults",get:function(){return e}}]),n}();M.FormSelect=t,M.jQueryLoaded&&M.initializeJqueryWrapper(t,"formSelect","M_FormSelect")}(cash),function(s,e){"use strict";var i={},t=function(t){function n(t,e){_classCallCheck(this,n);var i=_possibleConstructorReturn(this,(n.__proto__||Object.getPrototypeOf(n)).call(this,n,t,e));return(i.el.M_Range=i).options=s.extend({},n.defaults,e),i._mousedown=!1,i._setupThumb(),i._setupEventHandlers(),i}return _inherits(n,Component),_createClass(n,[{key:"destroy",value:function(){this._removeEventHandlers(),this._removeThumb(),this.el.M_Range=void 0}},{key:"_setupEventHandlers",value:function(){this._handleRangeChangeBound=this._handleRangeChange.bind(this),this._handleRangeMousedownTouchstartBound=this._handleRangeMousedownTouchstart.bind(this),this._handleRangeInputMousemoveTouchmoveBound=this._handleRangeInputMousemoveTouchmove.bind(this),this._handleRangeMouseupTouchendBound=this._handleRangeMouseupTouchend.bind(this),this._handleRangeBlurMouseoutTouchleaveBound=this._handleRangeBlurMouseoutTouchleave.bind(this),this.el.addEventListener("change",this._handleRangeChangeBound),this.el.addEventListener("mousedown",this._handleRangeMousedownTouchstartBound),this.el.addEventListener("touchstart",this._handleRangeMousedownTouchstartBound),this.el.addEventListener("input",this._handleRangeInputMousemoveTouchmoveBound),this.el.addEventListener("mousemove",this._handleRangeInputMousemoveTouchmoveBound),this.el.addEventListener("touchmove",this._handleRangeInputMousemoveTouchmoveBound),this.el.addEventListener("mouseup",this._handleRangeMouseupTouchendBound),this.el.addEventListener("touchend",this._handleRangeMouseupTouchendBound),this.el.addEventListener("blur",this._handleRangeBlurMouseoutTouchleaveBound),this.el.addEventListener("mouseout",this._handleRangeBlurMouseoutTouchleaveBound),this.el.addEventListener("touchleave",this._handleRangeBlurMouseoutTouchleaveBound)}},{key:"_removeEventHandlers",value:function(){this.el.removeEventListener("change",this._handleRangeChangeBound),this.el.removeEventListener("mousedown",this._handleRangeMousedownTouchstartBound),this.el.removeEventListener("touchstart",this._handleRangeMousedownTouchstartBound),this.el.removeEventListener("input",this._handleRangeInputMousemoveTouchmoveBound),this.el.removeEventListener("mousemove",this._handleRangeInputMousemoveTouchmoveBound),this.el.removeEventListener("touchmove",this._handleRangeInputMousemoveTouchmoveBound),this.el.removeEventListener("mouseup",this._handleRangeMouseupTouchendBound),this.el.removeEventListener("touchend",this._handleRangeMouseupTouchendBound),this.el.removeEventListener("blur",this._handleRangeBlurMouseoutTouchleaveBound),this.el.removeEventListener("mouseout",this._handleRangeBlurMouseoutTouchleaveBound),this.el.removeEventListener("touchleave",this._handleRangeBlurMouseoutTouchleaveBound)}},{key:"_handleRangeChange",value:function(){s(this.value).html(this.$el.val()),s(this.thumb).hasClass("active")||this._showRangeBubble();var t=this._calcRangeOffset();s(this.thumb).addClass("active").css("left",t+"px")}},{key:"_handleRangeMousedownTouchstart",value:function(t){if(s(this.value).html(this.$el.val()),this._mousedown=!0,this.$el.addClass("active"),s(this.thumb).hasClass("active")||this._showRangeBubble(),"input"!==t.type){var e=this._calcRangeOffset();s(this.thumb).addClass("active").css("left",e+"px")}}},{key:"_handleRangeInputMousemoveTouchmove",value:function(){if(this._mousedown){s(this.thumb).hasClass("active")||this._showRangeBubble();var t=this._calcRangeOffset();s(this.thumb).addClass("active").css("left",t+"px"),s(this.value).html(this.$el.val())}}},{key:"_handleRangeMouseupTouchend",value:function(){this._mousedown=!1,this.$el.removeClass("active")}},{key:"_handleRangeBlurMouseoutTouchleave",value:function(){if(!this._mousedown){var t=7+parseInt(this.$el.css("padding-left"))+"px";s(this.thumb).hasClass("active")&&(e.remove(this.thumb),e({targets:this.thumb,height:0,width:0,top:10,easing:"easeOutQuad",marginLeft:t,duration:100})),s(this.thumb).removeClass("active")}}},{key:"_setupThumb",value:function(){this.thumb=document.createElement("span"),this.value=document.createElement("span"),s(this.thumb).addClass("thumb"),s(this.value).addClass("value"),s(this.thumb).append(this.value),this.$el.after(this.thumb)}},{key:"_removeThumb",value:function(){s(this.thumb).remove()}},{key:"_showRangeBubble",value:function(){var t=-7+parseInt(s(this.thumb).parent().css("padding-left"))+"px";e.remove(this.thumb),e({targets:this.thumb,height:30,width:30,top:-30,marginLeft:t,duration:300,easing:"easeOutQuint"})}},{key:"_calcRangeOffset",value:function(){var t=this.$el.width()-15,e=parseFloat(this.$el.attr("max"))||100,i=parseFloat(this.$el.attr("min"))||0;return(parseFloat(this.$el.val())-i)/(e-i)*t}}],[{key:"init",value:function(t,e){return _get(n.__proto__||Object.getPrototypeOf(n),"init",this).call(this,this,t,e)}},{key:"getInstance",value:function(t){return(t.jquery?t[0]:t).M_Range}},{key:"defaults",get:function(){return i}}]),n}();M.Range=t,M.jQueryLoaded&&M.initializeJqueryWrapper(t,"range","M_Range"),t.init(s("input[type=range]"))}(cash,M.anime); \ No newline at end of file diff --git a/docs/en/1.1b2/_static/js/underscore.js b/docs/en/1.1b2/_static/js/underscore.js new file mode 100644 index 0000000..5b55f32 --- /dev/null +++ b/docs/en/1.1b2/_static/js/underscore.js @@ -0,0 +1,31 @@ +// Underscore.js 1.3.1 +// (c) 2009-2012 Jeremy Ashkenas, DocumentCloud Inc. +// Underscore is freely distributable under the MIT license. +// Portions of Underscore are inspired or borrowed from Prototype, +// Oliver Steele's Functional, and John Resig's Micro-Templating. +// For all details and documentation: +// http://documentcloud.github.com/underscore +(function(){function q(a,c,d){if(a===c)return a!==0||1/a==1/c;if(a==null||c==null)return a===c;if(a._chain)a=a._wrapped;if(c._chain)c=c._wrapped;if(a.isEqual&&b.isFunction(a.isEqual))return a.isEqual(c);if(c.isEqual&&b.isFunction(c.isEqual))return c.isEqual(a);var e=l.call(a);if(e!=l.call(c))return false;switch(e){case "[object String]":return a==String(c);case "[object Number]":return a!=+a?c!=+c:a==0?1/a==1/c:a==+c;case "[object Date]":case "[object Boolean]":return+a==+c;case "[object RegExp]":return a.source== +c.source&&a.global==c.global&&a.multiline==c.multiline&&a.ignoreCase==c.ignoreCase}if(typeof a!="object"||typeof c!="object")return false;for(var f=d.length;f--;)if(d[f]==a)return true;d.push(a);var f=0,g=true;if(e=="[object Array]"){if(f=a.length,g=f==c.length)for(;f--;)if(!(g=f in a==f in c&&q(a[f],c[f],d)))break}else{if("constructor"in a!="constructor"in c||a.constructor!=c.constructor)return false;for(var h in a)if(b.has(a,h)&&(f++,!(g=b.has(c,h)&&q(a[h],c[h],d))))break;if(g){for(h in c)if(b.has(c, +h)&&!f--)break;g=!f}}d.pop();return g}var r=this,G=r._,n={},k=Array.prototype,o=Object.prototype,i=k.slice,H=k.unshift,l=o.toString,I=o.hasOwnProperty,w=k.forEach,x=k.map,y=k.reduce,z=k.reduceRight,A=k.filter,B=k.every,C=k.some,p=k.indexOf,D=k.lastIndexOf,o=Array.isArray,J=Object.keys,s=Function.prototype.bind,b=function(a){return new m(a)};if(typeof exports!=="undefined"){if(typeof module!=="undefined"&&module.exports)exports=module.exports=b;exports._=b}else r._=b;b.VERSION="1.3.1";var j=b.each= +b.forEach=function(a,c,d){if(a!=null)if(w&&a.forEach===w)a.forEach(c,d);else if(a.length===+a.length)for(var e=0,f=a.length;e2;a== +null&&(a=[]);if(y&&a.reduce===y)return e&&(c=b.bind(c,e)),f?a.reduce(c,d):a.reduce(c);j(a,function(a,b,i){f?d=c.call(e,d,a,b,i):(d=a,f=true)});if(!f)throw new TypeError("Reduce of empty array with no initial value");return d};b.reduceRight=b.foldr=function(a,c,d,e){var f=arguments.length>2;a==null&&(a=[]);if(z&&a.reduceRight===z)return e&&(c=b.bind(c,e)),f?a.reduceRight(c,d):a.reduceRight(c);var g=b.toArray(a).reverse();e&&!f&&(c=b.bind(c,e));return f?b.reduce(g,c,d,e):b.reduce(g,c)};b.find=b.detect= +function(a,c,b){var e;E(a,function(a,g,h){if(c.call(b,a,g,h))return e=a,true});return e};b.filter=b.select=function(a,c,b){var e=[];if(a==null)return e;if(A&&a.filter===A)return a.filter(c,b);j(a,function(a,g,h){c.call(b,a,g,h)&&(e[e.length]=a)});return e};b.reject=function(a,c,b){var e=[];if(a==null)return e;j(a,function(a,g,h){c.call(b,a,g,h)||(e[e.length]=a)});return e};b.every=b.all=function(a,c,b){var e=true;if(a==null)return e;if(B&&a.every===B)return a.every(c,b);j(a,function(a,g,h){if(!(e= +e&&c.call(b,a,g,h)))return n});return e};var E=b.some=b.any=function(a,c,d){c||(c=b.identity);var e=false;if(a==null)return e;if(C&&a.some===C)return a.some(c,d);j(a,function(a,b,h){if(e||(e=c.call(d,a,b,h)))return n});return!!e};b.include=b.contains=function(a,c){var b=false;if(a==null)return b;return p&&a.indexOf===p?a.indexOf(c)!=-1:b=E(a,function(a){return a===c})};b.invoke=function(a,c){var d=i.call(arguments,2);return b.map(a,function(a){return(b.isFunction(c)?c||a:a[c]).apply(a,d)})};b.pluck= +function(a,c){return b.map(a,function(a){return a[c]})};b.max=function(a,c,d){if(!c&&b.isArray(a))return Math.max.apply(Math,a);if(!c&&b.isEmpty(a))return-Infinity;var e={computed:-Infinity};j(a,function(a,b,h){b=c?c.call(d,a,b,h):a;b>=e.computed&&(e={value:a,computed:b})});return e.value};b.min=function(a,c,d){if(!c&&b.isArray(a))return Math.min.apply(Math,a);if(!c&&b.isEmpty(a))return Infinity;var e={computed:Infinity};j(a,function(a,b,h){b=c?c.call(d,a,b,h):a;bd?1:0}),"value")};b.groupBy=function(a,c){var d={},e=b.isFunction(c)?c:function(a){return a[c]};j(a,function(a,b){var c=e(a,b);(d[c]||(d[c]=[])).push(a)});return d};b.sortedIndex=function(a, +c,d){d||(d=b.identity);for(var e=0,f=a.length;e>1;d(a[g])=0})})};b.difference=function(a){var c=b.flatten(i.call(arguments,1));return b.filter(a,function(a){return!b.include(c,a)})};b.zip=function(){for(var a=i.call(arguments),c=b.max(b.pluck(a,"length")),d=Array(c),e=0;e=0;d--)b=[a[d].apply(this,b)];return b[0]}}; +b.after=function(a,b){return a<=0?b():function(){if(--a<1)return b.apply(this,arguments)}};b.keys=J||function(a){if(a!==Object(a))throw new TypeError("Invalid object");var c=[],d;for(d in a)b.has(a,d)&&(c[c.length]=d);return c};b.values=function(a){return b.map(a,b.identity)};b.functions=b.methods=function(a){var c=[],d;for(d in a)b.isFunction(a[d])&&c.push(d);return c.sort()};b.extend=function(a){j(i.call(arguments,1),function(b){for(var d in b)a[d]=b[d]});return a};b.defaults=function(a){j(i.call(arguments, +1),function(b){for(var d in b)a[d]==null&&(a[d]=b[d])});return a};b.clone=function(a){return!b.isObject(a)?a:b.isArray(a)?a.slice():b.extend({},a)};b.tap=function(a,b){b(a);return a};b.isEqual=function(a,b){return q(a,b,[])};b.isEmpty=function(a){if(b.isArray(a)||b.isString(a))return a.length===0;for(var c in a)if(b.has(a,c))return false;return true};b.isElement=function(a){return!!(a&&a.nodeType==1)};b.isArray=o||function(a){return l.call(a)=="[object Array]"};b.isObject=function(a){return a===Object(a)}; +b.isArguments=function(a){return l.call(a)=="[object Arguments]"};if(!b.isArguments(arguments))b.isArguments=function(a){return!(!a||!b.has(a,"callee"))};b.isFunction=function(a){return l.call(a)=="[object Function]"};b.isString=function(a){return l.call(a)=="[object String]"};b.isNumber=function(a){return l.call(a)=="[object Number]"};b.isNaN=function(a){return a!==a};b.isBoolean=function(a){return a===true||a===false||l.call(a)=="[object Boolean]"};b.isDate=function(a){return l.call(a)=="[object Date]"}; +b.isRegExp=function(a){return l.call(a)=="[object RegExp]"};b.isNull=function(a){return a===null};b.isUndefined=function(a){return a===void 0};b.has=function(a,b){return I.call(a,b)};b.noConflict=function(){r._=G;return this};b.identity=function(a){return a};b.times=function(a,b,d){for(var e=0;e/g,">").replace(/"/g,""").replace(/'/g,"'").replace(/\//g,"/")};b.mixin=function(a){j(b.functions(a), +function(c){K(c,b[c]=a[c])})};var L=0;b.uniqueId=function(a){var b=L++;return a?a+b:b};b.templateSettings={evaluate:/<%([\s\S]+?)%>/g,interpolate:/<%=([\s\S]+?)%>/g,escape:/<%-([\s\S]+?)%>/g};var t=/.^/,u=function(a){return a.replace(/\\\\/g,"\\").replace(/\\'/g,"'")};b.template=function(a,c){var d=b.templateSettings,d="var __p=[],print=function(){__p.push.apply(__p,arguments);};with(obj||{}){__p.push('"+a.replace(/\\/g,"\\\\").replace(/'/g,"\\'").replace(d.escape||t,function(a,b){return"',_.escape("+ +u(b)+"),'"}).replace(d.interpolate||t,function(a,b){return"',"+u(b)+",'"}).replace(d.evaluate||t,function(a,b){return"');"+u(b).replace(/[\r\n\t]/g," ")+";__p.push('"}).replace(/\r/g,"\\r").replace(/\n/g,"\\n").replace(/\t/g,"\\t")+"');}return __p.join('');",e=new Function("obj","_",d);return c?e(c,b):function(a){return e.call(this,a,b)}};b.chain=function(a){return b(a).chain()};var m=function(a){this._wrapped=a};b.prototype=m.prototype;var v=function(a,c){return c?b(a).chain():a},K=function(a,c){m.prototype[a]= +function(){var a=i.call(arguments);H.call(a,this._wrapped);return v(c.apply(b,a),this._chain)}};b.mixin(b);j("pop,push,reverse,shift,sort,splice,unshift".split(","),function(a){var b=k[a];m.prototype[a]=function(){var d=this._wrapped;b.apply(d,arguments);var e=d.length;(a=="shift"||a=="splice")&&e===0&&delete d[0];return v(d,this._chain)}});j(["concat","join","slice"],function(a){var b=k[a];m.prototype[a]=function(){return v(b.apply(this._wrapped,arguments),this._chain)}});m.prototype.chain=function(){this._chain= +true;return this};m.prototype.value=function(){return this._wrapped}}).call(this); diff --git a/docs/en/1.1b2/_static/logo.svg b/docs/en/1.1b2/_static/logo.svg new file mode 100644 index 0000000..78bb2b4 --- /dev/null +++ b/docs/en/1.1b2/_static/logo.svg @@ -0,0 +1,42 @@ + + \ No newline at end of file diff --git a/docs/en/1.1b2/_static/pygments.css b/docs/en/1.1b2/_static/pygments.css new file mode 100644 index 0000000..5b510e8 --- /dev/null +++ b/docs/en/1.1b2/_static/pygments.css @@ -0,0 +1,77 @@ +pre { line-height: 125%; margin: 0; } +td.linenos pre { color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px; } +span.linenos { color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px; } +td.linenos pre.special { color: #000000; background-color: #ffffc0; padding-left: 5px; padding-right: 5px; } +span.linenos.special { color: #000000; background-color: #ffffc0; padding-left: 5px; padding-right: 5px; } +.highlight .hll { background-color: #49483e } +.highlight { background: #272822; color: #f8f8f2 } +.highlight .c { color: #75715e } /* Comment */ +.highlight .err { color: #960050; background-color: #1e0010 } /* Error */ +.highlight .k { color: #66d9ef } /* Keyword */ +.highlight .l { color: #ae81ff } /* Literal */ +.highlight .n { color: #f8f8f2 } /* Name */ +.highlight .o { color: #f92672 } /* Operator */ +.highlight .p { color: #f8f8f2 } /* Punctuation */ +.highlight .ch { color: #75715e } /* Comment.Hashbang */ +.highlight .cm { color: #75715e } /* Comment.Multiline */ +.highlight .cp { color: #75715e } /* Comment.Preproc */ +.highlight .cpf { color: #75715e } /* Comment.PreprocFile */ +.highlight .c1 { color: #75715e } /* Comment.Single */ +.highlight .cs { color: #75715e } /* Comment.Special */ +.highlight .gd { color: #f92672 } /* Generic.Deleted */ +.highlight .ge { font-style: italic } /* Generic.Emph */ +.highlight .gi { color: #a6e22e } /* Generic.Inserted */ +.highlight .go { color: #66d9ef } /* Generic.Output */ +.highlight .gp { color: #f92672; font-weight: bold } /* Generic.Prompt */ +.highlight .gs { font-weight: bold } /* Generic.Strong */ +.highlight .gu { color: #75715e } /* Generic.Subheading */ +.highlight .kc { color: #66d9ef } /* Keyword.Constant */ +.highlight .kd { color: #66d9ef } /* Keyword.Declaration */ +.highlight .kn { color: #f92672 } /* Keyword.Namespace */ +.highlight .kp { color: #66d9ef } /* Keyword.Pseudo */ +.highlight .kr { color: #66d9ef } /* Keyword.Reserved */ +.highlight .kt { color: #66d9ef } /* Keyword.Type */ +.highlight .ld { color: #e6db74 } /* Literal.Date */ +.highlight .m { color: #ae81ff } /* Literal.Number */ +.highlight .s { color: #e6db74 } /* Literal.String */ +.highlight .na { color: #a6e22e } /* Name.Attribute */ +.highlight .nb { color: #f8f8f2 } /* Name.Builtin */ +.highlight .nc { color: #a6e22e } /* Name.Class */ +.highlight .no { color: #66d9ef } /* Name.Constant */ +.highlight .nd { color: #a6e22e } /* Name.Decorator */ +.highlight .ni { color: #f8f8f2 } /* Name.Entity */ +.highlight .ne { color: #a6e22e } /* Name.Exception */ +.highlight .nf { color: #a6e22e } /* Name.Function */ +.highlight .nl { color: #f8f8f2 } /* Name.Label */ +.highlight .nn { color: #f8f8f2 } /* Name.Namespace */ +.highlight .nx { color: #a6e22e } /* Name.Other */ +.highlight .py { color: #f8f8f2 } /* Name.Property */ +.highlight .nt { color: #f92672 } /* Name.Tag */ +.highlight .nv { color: #f8f8f2 } /* Name.Variable */ +.highlight .ow { color: #f92672 } /* Operator.Word */ +.highlight .w { color: #f8f8f2 } /* Text.Whitespace */ +.highlight .mb { color: #ae81ff } /* Literal.Number.Bin */ +.highlight .mf { color: #ae81ff } /* Literal.Number.Float */ +.highlight .mh { color: #ae81ff } /* Literal.Number.Hex */ +.highlight .mi { color: #ae81ff } /* Literal.Number.Integer */ +.highlight .mo { color: #ae81ff } /* Literal.Number.Oct */ +.highlight .sa { color: #e6db74 } /* Literal.String.Affix */ +.highlight .sb { color: #e6db74 } /* Literal.String.Backtick */ +.highlight .sc { color: #e6db74 } /* Literal.String.Char */ +.highlight .dl { color: #e6db74 } /* Literal.String.Delimiter */ +.highlight .sd { color: #e6db74 } /* Literal.String.Doc */ +.highlight .s2 { color: #e6db74 } /* Literal.String.Double */ +.highlight .se { color: #ae81ff } /* Literal.String.Escape */ +.highlight .sh { color: #e6db74 } /* Literal.String.Heredoc */ +.highlight .si { color: #e6db74 } /* Literal.String.Interpol */ +.highlight .sx { color: #e6db74 } /* Literal.String.Other */ +.highlight .sr { color: #e6db74 } /* Literal.String.Regex */ +.highlight .s1 { color: #e6db74 } /* Literal.String.Single */ +.highlight .ss { color: #e6db74 } /* Literal.String.Symbol */ +.highlight .bp { color: #f8f8f2 } /* Name.Builtin.Pseudo */ +.highlight .fm { color: #a6e22e } /* Name.Function.Magic */ +.highlight .vc { color: #f8f8f2 } /* Name.Variable.Class */ +.highlight .vg { color: #f8f8f2 } /* Name.Variable.Global */ +.highlight .vi { color: #f8f8f2 } /* Name.Variable.Instance */ +.highlight .vm { color: #f8f8f2 } /* Name.Variable.Magic */ +.highlight .il { color: #ae81ff } /* Literal.Number.Integer.Long */ \ No newline at end of file diff --git a/docs/en/1.1b2/explanation.html b/docs/en/1.1b2/explanation.html new file mode 100644 index 0000000..4dd7afb --- /dev/null +++ b/docs/en/1.1b2/explanation.html @@ -0,0 +1,240 @@ + + + + + + + + Explanation - GINO 1.1.0b2 documentation + + + + + + + + + + + +

+ +

+ + + + + +

+ + + +

+ + HOME + + + CREDITS + + +

Tutorials

How-to Guides

Explanation

Reference

+ +

Explanation¶

+ +

+ + +

+ + + +
+ This work is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License. +

+ +

Explanation

+ + +

+ Add your language here. +

+ +

+ +

+ + + + + + + + + + + \ No newline at end of file diff --git a/docs/en/1.1b2/explanation/async.html b/docs/en/1.1b2/explanation/async.html new file mode 100644 index 0000000..c5b1e45 --- /dev/null +++ b/docs/en/1.1b2/explanation/async.html @@ -0,0 +1,375 @@ + + + + + + + + Asynchronous Programming 101 - GINO 1.1.0b2 documentation + + + + + + + + + + + +

+ + +

Tutorials

How-to Guides

Explanation

Reference

+ +

Asynchronous Programming 101¶

The Story¶

We have lots of web pages to index, so we simply handle them one by one:

There are yellow bars taking up extra time.
The green bars can still overlap with any bar in the other thread, but
non-green bars cannot overlap with non-green bars in the other thread.

Note

Asynchronous I/O and coroutines are two different things, but they usually +go together. Here we will stick with coroutines for simplicity.

Cooperative multitasking¶

So what is a coroutine?

Thread 1: I wanna run!
+OS: Okay, here you go...
+Thread 2: I wanna run!
+OS: Urh, alright one sec ... Thread 1, hold on for a while!
+Thread 1: Well I'm not done yet, but you are the boss.
+OS: It won't be long. Thread 2 it's your turn now.
+Thread 2: Yay! (&%#$@..+*&#)
+Thread 1: Can I run now?
+OS: Just a moment please ... Thread 2, give it a break!
+Thread 2: Alright ... but I really need the CPU.
+OS: You'll have it later. Thread 1, hurry up!
+

+

Coroutine 1: Let me know when event A arrives. I'm done here before that.
+Event manager: Okay. What about you, coroutine 2?
+Coroutine 2: Um I've got nothing to do here before event B.
+Event manager: Cool, I'll be watching.
+Event manager: (after a while) Hey coroutine 1, event A is here!
+Coroutine 1: Awesome! Let me see ... looks good, but I need event C now.
+Event manager: Very well. Seems event B arrived just now, coroutine 2?
+Coroutine 2: Oh wonderful! Let me store it in a file ... There! I'm all done.
+Event manager: Sweet! Since there's no sign of event C yet, I'll sleep for a while.
+(silence)
+Event manager: Damn, event C timed out!
+Coroutine 1: Arrrrh gotta kill myself with an exception :S
+Event manager: Up to you :/
+

+

Tip

In Python and asyncio, async def declares coroutines, await yields +control to event loop (event manager).

Pros and cons¶

With coroutines, you can naturally write sequential code that is cooperatively +scheduled. If your business logic is complex, coroutines could greatly improve +readability of asynchronous I/O code.

+ + +

+ + + +
+ This work is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License. +

+ +

Asynchronous Programming 101
- The Story
- Cooperative multitasking
- Pros and cons
+

+ + +

+ +

+ + +

+ Add your language here. +

+ +

+ +

+ + + + + + + + + + + \ No newline at end of file diff --git a/docs/en/1.1b2/explanation/engine.html b/docs/en/1.1b2/explanation/engine.html new file mode 100644 index 0000000..07fd9ca --- /dev/null +++ b/docs/en/1.1b2/explanation/engine.html @@ -0,0 +1,682 @@ + + + + + + + + Engine and Connection - GINO 1.1.0b2 documentation + + + + + + + + + + + +

+ + +

Tutorials

How-to Guides

Explanation

Reference

+ +

Engine and Connection¶

GinoEngine is the core of GINO. It acts like a pool of +connections but also does the work of assembling everyone together:

Note

By immediately releasing a connection, GINO may not release the related raw +connection when the raw connection was reused from another parent +connection. We’ll get to this later.

Then let’s get to some details.

Creating Engines¶

GINO reuses the strategy system SQLAlchemy provides to create engines. The name +of GINO’s strategy to create asynchronous GinoEngine is +just gino, but only available after gino is imported:

import gino, sqlalchemy
+
+async def main():
+    e = await sqlalchemy.create_engine('postgresql://...', strategy='gino')
+    # e is a GinoEngine
+

+

Tip

Please read this SQLAlchemy document +to learn about writing database URLs.

GINO also offers a shortcut as gino.create_engine(), which only sets the +default strategy to gino and does nothing more. So here is an identical +example:

import gino
+
+async def main():
+    e = await gino.create_engine('postgresql://...')
+    # e is also a GinoEngine
+

+

For Dialect:

isolation_level
paramstyle

For Engine:

While these parameters are discarded by GINO:

module

e = await gino.create_engine('postgresql://...', min_size=0)
+

+

Similar to SQLAlchemy, GINO also provides shortcut to create engine while +setting it as a bind. In SQLAlchemy it is like this:

import sqlalchemy
+
+metadata = sqlalchemy.MetaData()
+metadata.bind = 'postgresql://...'
+
+# or in short
+
+metadata = sqlalchemy.MetaData('postgresql://...')
+

+

import gino
+
+db = gino.Gino()
+
+async def main():
+    # db.bind = 'postgresql://...' doesn't work!! It sets a string on bind
+    engine = await gino.create_engine('postgresql://...')
+    db.bind = engine
+

+

And provided a shortcut to do so:

engine = await db.set_bind('postgresql://...')
+

+

And another simpler shortcut for one-time usage:

db = await gino.Gino('postgresql://...')
+

+

To unset a bind and close the engine:

engine, db.bind = db.bind, None
+await engine.close()
+

+

Or with a shortcut correspondingly:

await engine.pop_bind().close()
+

+

Furthermore, the two steps can be combined into one shortcut with asynchronous +context manager:

async with db.with_bind('postgresql://...') as engine:
+    # your code here
+

+

Managing Connections¶

With a GinoEngine at hand, you can acquire connections +from the pool now:

conn = await engine.acquire()
+

+

Don’t forget to release it after use:

await conn.release()
+

+

Yes this can be easily missing. The recommended way is to use the asynchronous +context manager:

async with engine.acquire() as conn:
+    # play with the connection
+

+

Here conn is a GinoConnection instance. As mentioned +previously, GinoConnection is mapped to an underlying raw +connection, as shown in following diagram:

reuse¶

async with engine.acquire() as conn1:
+    async with engine.acquire() as conn2:
+        # conn2 is a completely different connection than conn1
+

+

But sometimes conn2 may exist in a different method:

async def outer():
+    async with engine.acquire() as conn1:
+        await inner()
+
+async def inner():
+    async with engine.acquire() as conn2:
+        # ...
+

+

And we probably wish inner could reuse the same raw connection in +outer to save some resource, or borrow a new one if inner is +individually called without outer:

async def outer():
+    async with engine.acquire() as conn1:
+        await inner(conn1)
+
+async def inner(conn2=None):
+    if conn2 is None:
+        async with engine.acquire() as conn2:
+            # ...
+    else:
+        # the same ... again
+

+

async def outer():
+    async with engine.acquire() as conn1:
+        await inner(conn1)
+
+async def inner():
+    async with engine.acquire(reuse=True) as conn2:
+        # ...
+

+

Tip

GinoConnection (2) may be created through +acquire(reuse=True) too - because the stack is empty before (2), there is +nothing to reuse, so (2) upgraded itself to a reusable connection.

lazy¶

As you may have found, GinoConnection (5) does not have +an underlying raw connection, even when it is reused by (6). This is because +both (5) and (6) set lazy=True on acquire.

async with engine.acquire(lazy=True) as conn:  # (7)
+    await conn.scalar('select now()')          # (8)
+

+

async with engine.acquire(lazy=True) as conn:  # (7)
+    await conn.scalar('select now()')          # (8)
+    await conn.release(permanent=False)        # release (8)
+    await asyncio.sleep(10)                    # simulate long I/O work
+    await conn.scalar('select now()')          # re-acquire a new raw connection,
+                                               #   not necessarily the same (8)
+

+

reusable¶

async with engine.acquire():                    # (2)
+    async with engine.acquire(reusable=False):  # the unreusable connection
+        async with engine.acquire(reuse=True):  # (3)
+

+

current_connection¶

Tip

The different between current_connection +and acquire(reuse=True) is, the +latter always produces a GinoConnection, while the +former may not.

Executing Queries¶

all() returns all results in a +list, which may be empty when the query has no result, empty but +still a list.
first() returns the first result directly, +or None if there is no result at all. There is usually some optimization +behind the scene to efficiently get only the first result, instead of loading +the full result set into memory.
one() returns exactly one result. If there +is no result at all or if there are multiple results, an exception is raised.
one_or_none() is similar to +one(), but it returns None if there is +no result instead or raising an exception.
scalar() is similar to +first(), it returns the first value of the +first result. Quite convenient to just retrieve a scalar value from database, +like NOW(), MAX(), COUNT() or whatever generates a single value. +None is also returned when there is no result, it is up to you how to +distinguish no result and the first value is NULL.
status() executes the query and discard all +the query results at all. Instead it returns the execution status line as it +is, usually a textual string. Note, there may be no optimization to only +return the status without loading the results, so make your query generate +nothing if you don’t want any result.

Implicit Execution¶

await engine.scalar('select now()')
+

+

Equals to:

async with engine.acquire(reuse=True) as conn:
+    await conn.scalar('select now()')
+

+

This allows you to easily write connectionless code. For example:

async def get_now():
+    return await engine.scalar('select now()')
+
+async def main():
+    async with engine.acquire():
+        now = await get_now()
+        await engine.status('UPDATE ...')
+

+

In this example, main() will take only one raw connection. get_now() +can also work alone out of any acquire() context, thanks to reuse.

Furthermore, GINO provides the same query APIs on Gino +directly. They are simply delegates to corresponding API methods on the +bind. This allows even engine-less programming:

db = gino.Gino()
+
+async def get_now():
+    return await db.scalar('select now()')
+
+async def main():
+    async with db.with_bind('postgresql://...'):
+        now = await get_now()
+        await db.status('UPDATE ...')
+

+

Note

In this example we didn’t put the two queries in an acquire() block, so +they might be executed in two different connections.

At last, the SQLAlchemy implicit execution +on queries also work in GINO, under an extension named gino:

await users_table.select().gino.all()
+

+

+ + +

+ + + +
+ This work is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License. +

+ +

Engine and Connection
- Creating Engines
- Managing Connections
  - reuse
  - lazy
  - reusable
  - current_connection
  +
- Executing Queries
- Implicit Execution
+

+ + +

+ +

+ + +

+ Add your language here. +

+ +

+ +

+ + + + + + + + + + + \ No newline at end of file diff --git a/docs/en/1.1b2/explanation/sa20.html b/docs/en/1.1b2/explanation/sa20.html new file mode 100644 index 0000000..d320a35 --- /dev/null +++ b/docs/en/1.1b2/explanation/sa20.html @@ -0,0 +1,824 @@ + + + + + + + + SQLAlchemy 2.0 - GINO 1.1.0b2 documentation + + + + + + + + + + + +

+ +

+ + + + + + + +

+ + + +

+ + HOME + + + CREDITS + + +

Tutorials

How-to Guides

Explanation

Reference

+ +

SQLAlchemy 2.0¶

This article explains the new updates from SQLAlchemy 1.4 and 2.0, as well as how GINO +adapts to such changes.

SQLAlchemy 2.0 will +deliver many breaking API changes, and SQLAlchemy 1.4 will be the “interim” +version for people to eventually upgrade their software to use SQLAlchemy 2.0.

+ ++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

GINO	SQLAlchemy	Dialect	Comments
1.0.x	1.3.x	Custom	Current (old-)stable.
1.1.x	1.3.x	Custom	Next old-stable.
1.2.x	1.3.x	Custom	Future old-stable (maybe).
1.4.x	1.4.x	Upstream	2.0 Interim.
2.0.x	2.0.x	Upstream	Future stable.
2.1.x	2.0.x	Upstream	Future stable iterations.

To make things easier, GINO will (luckily) also follow the same versions for the transition. That is, +GINO 1.4 will be requiring SQLAlchemy 1.4, providing similar pre-1.4-compatible APIs +with deprecations and options to switch to 2.0-API; GINO 2.0 needs SQLAlchemy 2.0 and +provides new APIs only.

At the same time, GINO 1.1, 1.2 and 1.3 will be reserved as the old-stable versions with +new features added on SQLAlchemy 1.3. And GINO post-2.0 won’t match SQLAlchemy versions.

The Async Solution¶

Among all the exciting updates in SQLAlchemy 1.4 / 2.0, native async support is the most +significant change for GINO. Simply speaking, SQLAlchemy 1.4 decided to make use of +greenlet to mix asynchronous stuff into current code base, avoiding making everything +async.

Let’s say we have an asynchronous method to create an asyncpg connection:

import asyncpg
+
+async def connect():
+    return await asyncpg.connect("postgresql:///")
+

+

And an end-user method to use it:

async def main():
+    conn = await connect()
+    now = await conn.fetchval("SELECT now()")
+

+

Now instead of directly calling connect() from main(), I would like to add some +additional logic - let’s say, a sanity check:

async def safe_connect():
+    conn = await connect()
+    try:
+        await conn.execute("SELECT 1")
+    except Exception:
+        return None
+    else:
+        return conn
+

+

Then the end-user should modify main() to:

 async def main():
+     conn = await safe_connect()
+     if conn:
+         now = await conn.fetchval("SELECT now()")
+

+

OK, everything works so far, as they are all regular async code. Here’s the interesting +part: safe_connect() must not be an async def method. With SQLAlchemy 1.4+, we +could:

 from sqlalchemy.util import await_only, greenlet_spawn
+
+ def sync_safe_connect():
+     conn = await_only(connect())
+     try:
+         await_only(conn.execute("SELECT 1"))
+     except Exception:
+         return None
+     else:
+         return conn
+
+ async def safe_connect():
+     return await greenlet_spawn(sync_safe_connect)
+

+

Behind the scene, greenlet_spawn() runs the given “sync” method in a greenlet, which +uses await_only() to switch to the event loop and bridge the underlying async +methods. As sync_safe_connect() is just a normal Python method, you can imagine how +it works together with lots of other “sync” code asynchronously.

We’re not going deeper into the implementation, but this is basically how SQLAlchemy 1.4 +mixes asyncpg driver into its “sync” code base, and still being able to provide async +APIs on top of them.

Async SQLAlchemy¶

Although greenlet might be the only way to practically port SQLAlchemy to the async +world natively without having to maintain 2 copies of the same code, introducing +implicit asynchronous to a large sync code base is still a risky move.

The sync library existed for years, with many assumptions like using threading.Lock +to control concurrency. When switching to asynchronous programming, such primitives and +assumptions usually need to be reviewed and probably replaced by e.g. asyncio.Lock. +However, the implicit approach is so convenient that most of the blocking code just +works without any changes at all, lowering the odds to review and find possible issues.

As a matter of fact, some issues can only be revealed under (heavy) concurrency. For +example, threading.Lock.acquire() actually works fine in a single coroutine, but 2 +concurrent coroutines +acquiring the same threading.Lock may easily block the main thread forever. The same +applies to data structures like queues, etc. In short, there must be nothing to block +the main thread.

Lastly, having implicit asynchronous is a potential maintenance risk. Because the +context switches are usually hidden behind regular sync methods, it is easy to forget +such methods may lead to concurrency issues. Treating coroutines as OS threads is a good +idea and it usually works, but they are fundamentally different. Extra care is always +needed when trying to support both sync and async with the same code base.

However, such risks are mostly contained within SQLAlchemy itself. End-users are still +using regular explicit asynchronous APIs to leverage the async DB drivers. With proper +reviewing, testing and sufficient community exposure (that’s GINO’s part), it is still +possible and reliable to have a single SQLAlchemy with 2 sets of APIs (sync + async). +For sure, the APIs are not 100% identical - for example, the ORM lazy-loading won’t work +because there is no place for await in accessing attributes (GINO doesn’t like such +implicitness anyways, so yeah).

To quickly get a picture of async SQLAlchemy (Core), here’s a sample from SQLAlchemy:

import asyncio
+
+from sqlalchemy.ext.asyncio import create_async_engine
+
+async def async_main():
+    engine = create_async_engine(
+        "postgresql+asyncpg://scott:tiger@localhost/test", echo=True,
+    )
+
+    async with engine.begin() as conn:
+        await conn.run_sync(meta.drop_all)
+        await conn.run_sync(meta.create_all)
+
+        await conn.execute(
+            t1.insert(), [{"name": "some name 1"}, {"name": "some name 2"}]
+        )
+
+    async with engine.connect() as conn:
+
+        # select a Result, which will be delivered with buffered
+        # results
+        result = await conn.execute(select(t1).where(t1.c.name == "some name 1"))
+
+        print(result.fetchall())
+
+
+asyncio.run(async_main())
+

+

Auto-Commit Complication¶

After using PostgreSQL for a long time, I took many features for granted. The +auto-commit feature is one of them. We all know that BEGIN starts a transaction and +COMMIT / ROLLBACK ends it. But what is happening to SQL statements that is not +wrapped in BEGIN ... COMMIT blocks?

+
If you do not issue a BEGIN command, then each individual statement has an +implicit BEGIN and (if successful) COMMIT wrapped around it.
+
—PostgreSQL Documentation, 3.4. Transactions
+

And yes, implicit ROLLBACK if not successful. This is not directly named as an +“auto-commit” feature, but PostgreSQL does enforce it. Now imagine a database whose +“auto-commit” feature can be turned off - such individual statements are either executed +without ACID-transactions at all (no surprise, there are databases without ACID :doge:), +or the session is left with a open-ended transaction to be further committed.

PEP 249 (DB-API 2.0) - the standard for +Python database drivers - was created in such background stories. The assumption it made +appears to me like, the database may probably not support ACID; if it does, auto-commit +is usually not supported. Because it defined only commit() and rollback() on a +connection, but no begin(). So I think DB-API assumes that, when executing +statements, the connection is automatically put in a transaction (if ACID is supported), +and you have to call commit() to persist your changes. Closing a connection will +cause pending transactions rolled back automatically.

+
Note that if the database supports an auto-commit feature, this (the auto-commit +feature – GINO comments) must be initially off.
+
—PEP 249
+

As the API behavior is defined, database drivers for even e.g. PostgreSQL with enforced +“auto-commit” has to mimic such behavior. For example, psycopg2 will automatically emit +a BEGIN to the database upon the first execution by default, so that such execution +is not auto-committed. The implicit transaction boundary is a very evil thing - people +constantly leaves transactions open (ever seen IDLE IN TRANSACTION?), sometimes even +holding database locks and eventually causing a deadlock storm.

To work around this workaround, PEP 249 does say:

+
An interface method may be provided to turn it (the auto-commit feature) back on.
+

So for psycopg2, one could do this:

import psycopg2
+
+conn = psycopg2.connect("postgresql:///")
+conn.autocommit = True
+conn.cursor().execute("SELECT now()")
+

+

Now the database correctly receives this SELECT statement only, without any implicit +BEGIN surprises. But when we want to have explicit transactions, DB-API only gives +us 2 options: 1) Do it manually:

conn.cursor().execute("BEGIN")
+conn.cursor().execute("UPDATE ...")
+conn.cursor().execute("COMMIT")
+

+

Or 2) turn auto-commit off again:

conn.autocommit = False
+conn.cursor().execute("UPDATE ...")
+conn.commit()
+

+

I know this is frustrating (or maybe people have accepted it), but newer database +drivers like asyncpg does provide a cleaner API, by not complying to PEP 249:

import asyncpg
+
+async def main():
+    conn = await asyncpg.connect("postgresql://")
+
+    print(await conn.fetchval("SELECT now()"))  # SELECT now();
+
+    async with conn.transaction():              # BEGIN;
+        await conn.execute("UPDATE ...")        # UPDATE ...;
+                                                # COMMIT;
+

+

It’s much cleaner to see what’s actually happening on the wire to the database. This is +also how GINO works.

SQLAlchemy for DB-API¶

Because SQLAlchemy is built on PEP 249 (DB-API 2.0), its API is also greatly affected by +the PEP standard. For example, imagine what SQL is actually executed by this code:

import sqlalchemy as sa
+
+e = sa.create_engine("postgresql:///", future=True)
+with e.connect() as conn:
+    conn.scalar(sa.text("SELECT now()"))
+

+

Only SELECT now()? No. Here’s the answer:

with e.connect() as conn:                 # BEGIN; SELECT version(); ...; ROLLBACK;
+    conn.scalar(sa.text("SELECT now()"))  # BEGIN; SELECT now();
+                                          # ROLLBACK;
+

+

Note

We are using SQLAlchemy 2.0 API for simplification, by setting future=True using +SQLAlchemy 1.4. It’s way more complicated in SQLAlchemy 1.3 and I don’t want to get +into that.

The reason behind this is, connections have “auto-commit” turned off by default. If +there is no transaction, an implicit BEGIN will be automatically executed upon the +first statement. This applies to async SQLAlchemy too - even if the underlying asyncpg +is not DB-API-compliant, the AsyncpgDialect in SQLAlchemy still wrapped asyncpg and +simulated a compatible DB-API. Like this:

import sqlalchemy as sa
+from sqlalchemy.ext.asyncio import create_async_engine
+
+async def main():
+    e = create_async_engine("postgresql+asyncpg:///")
+    async with e.connect() as conn:                  # BEGIN; SELECT version(); ...; ROLLBACK;
+        await conn.execute(sa.text("SELECT now()"))  # BEGIN; SELECT now();
+                                                     # ROLLBACK;
+

+

If you want to modify the database permanently, you have to commit() the implicit +transaction explicitly:

 async def main():
+     e = ...
+     async with e.connect() as conn:
+         await conn.execute(sa.text("UPDATE ..."))    # BEGIN; UPDATE ...;
+         await conn.commit()                          # COMMIT;
+

+

Or use the explicit transaction API:

 async def main():
+     e = ...
+     async with e.connect() as conn:
+         async with conn.begin():                     # BEGIN;
+             await conn.execute(sa.text("UPDATE.."))  # UPDATE ...;
+                                                      # COMMIT;
+

+

Please note that, SQLAlchemy 2.0 doesn’t allow soft-nested transactions. In other words, +you cannot nest 2 async with conn.begin(): blocks like this:

 async def main():
+     e = ...
+     async with e.connect() as conn:
+         async with conn.begin():      # BEGIN;
+             async with conn.begin():  # Error: a transaction is already begun
+                 ...
+

+

This limitation applies to implicit transactions too, even though it’s weird:

 async def main():
+     e = ...
+     async with e.connect() as conn:
+         await conn.execute(sa.text("SELECT now()"))  # BEGIN; SELECT now();
+         async with conn.begin():  # Error: a transaction is already begun
+             ...
+

+

You have to explicitly close this implicit transaction in order for an explicit +transaction to start successfully:

 async def main():
+     e = ...
+     async with e.connect() as conn:
+         await conn.execute(sa.text("SELECT now()"))  # BEGIN; SELECT now();
+         await conn.rollback()                        # ROLLBACK;
+         async with conn.begin():                     # BEGIN;
+             await conn.execute(sa.text("UPDATE.."))  # UPDATE ...;
+                                                      # COMMIT;
+

+

Similar to Core, SQLAlchemy ORM follows the same principal. Grab a session, use +it without begin(), and when you want to commit, commit(). Or, use an explicit +transaction in a with session.begin(): block. Personally I don’t like that much, but +it is how SQLAlchemy manages transactions. Please follow the link above to read more.

SQLAlchemy AUTOCOMMIT¶

I know you already miss the WYSIWYG asyncpg and GINO API. Hang in there, let’s build +GINO 1.4 together with the SQLAlchemy AUTOCOMMIT feature.

To turn AUTOCOMMIT back on, we need to set the isolation_level to AUTOCOMMIT in +execution_options:

 async def main():
+     e = create_async_engine(
+         "postgresql+asyncpg:///",
+         execution_options={"isolation_level": "AUTOCOMMIT"},
+     )
+     async with e.connect() as conn:
+         await conn.execute(sa.text("SELECT now()"))  # SELECT now();
+

+

Hooray! No more implicit BEGIN magic. We’re one step closer.

Note

There is also a keyword argument:

 e = create_async_engine(
+     "postgresql+asyncpg:///",
+     isolation_level="AUTOCOMMIT",
+ )
+

+

But this is implemented very differently than execution_options, and I don’t +think it’s working for GINO’s use case.

The next question is, how do we explicitly start a transaction? Let’s try begin():

 async def main():
+     e = ...
+     async with e.connect() as conn:
+         await conn.execute(sa.text("SELECT now()"))  # SELECT now();
+         async with conn.begin():  # Error: a transaction is already begun
+             ...
+

+

Wait a second … we’ve seen this error before! It is the implicit transaction +conflicting with the explicit transaction. But I thought we’re in AUTOCOMMIT mode? Even +though the isolation_level tell the driver not to send BEGIN to the database, +SQLAlchemy still manages library-level transaction objects. We have to close the virtual +implicit transaction before starting an explicit transaction:

 async def main():
+     e = ...
+     async with e.connect() as conn:
+         await conn.execute(sa.text("SELECT now()"))  # SELECT now();
+         await conn.rollback()                        # no-op
+         async with conn.begin():                     # no-op
+             await conn.execute(sa.text("UPDATE.."))  # UPDATE ...;
+

+

Well, not quite what we expected. With AUTOCOMMIT set, all of begin(), commit() +and rollback() become no-ops.

Similar to the answers in psycopg2, we have 2 options here too: 1) manually execute +transaction-control SQLs, or 2) turn off AUTOCOMMIT temporarily. As we want to be more +compatible with SQLAlchemy, let’s try 2):

 async def main():
+     e = ...
+     async with e.connect() as conn:
+         await conn.execute(sa.text("SELECT now()"))  # SELECT now();
+         await conn.rollback()                        # no-op
+         async with conn.execution_options(
+             isolation_level="READ COMMITTED"
+         ).begin():                                   # BEGIN;
+             await conn.execute(sa.text("UPDATE.."))  # UPDATE ...;
+                                                      # COMMIT;
+

+

It’s working! According to SQLAlchemy docs, execution_options() creates a shallow +copy of the connection, and apply new values only to the copy. So the original +connection should still be in AUTOCOMMIT, right? Well…

 async def main():
+     e = ...
+     async with e.connect() as conn:
+         ...
+         async with conn.execution_options(
+             isolation_level="READ COMMITTED"
+         ).begin():                                   # BEGIN;
+             await conn.execute(sa.text("UPDATE.."))  # UPDATE ...;
+                                                      # COMMIT;
+
+         await conn.execute(sa.text("SELECT now()"))  # BEGIN; SELECT now();
+                                                      # ROLLBACK;
+

+

Unfortunately, the implicit transaction is haunting us again. This is because both the +original connection and its shallow copy points to the same “DB-API” connection (in this +case, a SQLAlchemy wrapper of asyncpg connection), and setting isolation_level +modifies the value on “DB-API” connection.

Returning a SQLAlchemy connection back to the pool resets the isolation_level to its +default value, and acquiring the same connection again will initialize the +isolation_level with values from execution_options of the engine. But if we want +to keep using the same connection without returning, we have to manually overwrite its +isolation_level again:

 async def main():
+     e = ...
+     async with e.connect() as conn:
+         ...
+         async with conn.execution_options(
+             isolation_level="READ COMMITTED"
+         ).begin():                                   # BEGIN;
+             await conn.execute(sa.text("UPDATE.."))  # UPDATE ...;
+                                                      # COMMIT;
+
+         conn.execution_options(isolation_level="AUTOCOMMIT")
+         await conn.execute(sa.text("SELECT now()"))  # SELECT now();
+

+

Eventually we made it! 🎉

Encapsulating all such logic, GINO 1.4 could then provide decent WYSIWYG APIs again:

import gino
+
+async def main():
+    engine = await gino.create_engine("postgresql:///")
+    async with engine.acquire() as conn:
+        await conn.scalar("SELECT now()")    # SELECT now();
+
+        async with conn.transaction():       # BEGIN;
+            await conn.status("UPDATE ...")  # UPDATE ...;
+                                             # COMMIT;
+

+

Hint

Now I feel that “implementing” auto-commit feature is more like restoring to the +original database behavior, and having auto-commit turned off by default should be +considered as a new feature called “auto-begin” or “implicit transaction”. And it’s +a bad design introduced in early PEP 249, affecting SQLAlchemy and the ecosystem.

Isolation Levels¶

By far, we only used 2 isolation_level values:

AUTOCOMMIT
READ COMMITTED

AUTOCOMMIT is not a valid PostgreSQL isolation level. It’s only recognized and +consumed by the SQLAlchemy asyncpg dialect to bypass the “auto-begin” simulation.

READ COMMITTED is the default PostgreSQL isolation level. You can verify this by +executing a SQL directly in a transaction:

# BEGIN;
+BEGIN
+
+# SHOW TRANSACTION ISOLATION LEVEL;
+ transaction_isolation
+-----------------------
+ read committed
+(1 row)
+
+# ROLLBACK;
+ROLLBACK
+

+

To start a transaction in a different isolation level, you may:

 # BEGIN ISOLATION LEVEL SERIALIZABLE;
+ BEGIN
+
+ # SHOW TRANSACTION ISOLATION LEVEL;
+  transaction_isolation
+ -----------------------
+  serializable
+ (1 row)
+
+ # ROLLBACK;
+ ROLLBACK
+

+

As mentioned earlier, all PostgreSQL statements are executed in a transaction. If no +explicit BEGIN in place, an implicit transaction is used. So this SQL also works +individually:

# SHOW TRANSACTION ISOLATION LEVEL;
+ transaction_isolation
+-----------------------
+ read committed
+(1 row)
+

+

But how could we modify the isolation level of such implicit transactions? The answer is +to set isolation level session-wise. This affects all subsequent transactions, including +both implicit and explicit ones, except for explicit transactions with explicit +isolation levels:

 # SET SESSION CHARACTERISTICS AS TRANSACTION ISOLATION LEVEL SERIALIZABLE;
+ SET
+
+ # SHOW TRANSACTION ISOLATION LEVEL;
+  transaction_isolation
+ -----------------------
+  serializable
+ (1 row)
+
+ # BEGIN;
+ BEGIN
+
+ # SHOW TRANSACTION ISOLATION LEVEL;
+  transaction_isolation
+ -----------------------
+  serializable
+ (1 row)
+
+ # ROLLBACK;
+ ROLLBACK
+
+ # BEGIN ISOLATION LEVEL READ COMMITTED;
+ BEGIN
+
+ # SHOW TRANSACTION ISOLATION LEVEL;
+  transaction_isolation
+ -----------------------
+  read committed
+ (1 row)
+
+ # ROLLBACK;
+ ROLLBACK
+

+

Then let’s see how SQLAlchemy with asyncpg solves this problem:

 async def main():
+     e = create_async_engine(
+         "postgresql+asyncpg:///",
+         execution_options={"isolation_level": "SERIALIZABLE"},
+     )
+     async with e.connect() as conn:
+         async with conn.begin():  # BEGIN ISOLATION LEVEL SERIALIZABLE;
+             await conn.execute(sa.text("UPDATE ..."))  # UPDATE ...;
+                                                        # COMMIT;
+

+

Under the neath, SQLAlchemy is leveraging asyncpg’s +Connection.transaction(isolation="...") to set isolation level per transaction. In +GINO, we just need to store the user-defined isolation level, and set before +transactions.

But there are 2 issues:

User-defined isolation level is not applied in PostgreSQL implicit transactions +(a.k.a. auto-commit statements), because no one SET SESSION.
asyncpg has a bug that Connection.transaction(isolation="read_committed") always +emit BEGIN without explicit isolation level, regardless of the actual default +isolation level.

The asyncpg bug should be fixed from upstream, but we could leverage a session-wide +isolation level setter from base SQLAlchemy dialect for PostgreSQL:

 import sqlalchemy as sa
+ from sqlalchemy import event
+ from sqlalchemy.dialects.postgresql.base import PGDialect
+ from sqlalchemy.ext.asyncio import create_async_engine
+
+
+ async def main():
+     e = create_async_engine(
+         "postgresql+asyncpg:///",
+         execution_options={"isolation_level": "AUTOCOMMIT"},
+     )
+
+     def set_isolation_level(dbapi_conn, record):
+         PGDialect.set_isolation_level(
+             e.sync_engine.dialect,
+             dbapi_conn,
+             "SERIALIZABLE",
+         )
+
+     event.listen(e.sync_engine, "connect", set_isolation_level)
+
+     async with e.connect() as conn:
+         print(await conn.scalar(sa.text("SHOW TRANSACTION ISOLATION LEVEL")))
+         # Outputs: serializable
+

+

+ + +

+ + + +
+ This work is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License. +

+ +

SQLAlchemy 2.0
+

+ + +

+ +

+ + +

+ Add your language here. +

+ +

+ +

+ + + + + + + + + + + \ No newline at end of file diff --git a/docs/en/1.1b2/explanation/why.html b/docs/en/1.1b2/explanation/why.html new file mode 100644 index 0000000..f54785a --- /dev/null +++ b/docs/en/1.1b2/explanation/why.html @@ -0,0 +1,410 @@ + + + + + + + + Why Asynchronous ORM? - GINO 1.1.0b2 documentation + + + + + + + + + + + +

+ + +

Tutorials

How-to Guides

Explanation

Reference

+ +

Why Asynchronous ORM?¶

Conclusion first: in many cases, you don’t need to use an asynchronous ORM, or even +asyncio itself. But when you do, it’s very important to get it done correctly.

When asyncio Helps¶

In closing, there are scenarios when asyncio could help with concurrency issues. Now +that we know we will write an asynchronous server, then the next question is:

How to Access Database¶

import asyncio
+from fastapi import FastAPI
+from sqlalchemy import create_engine
+from sqlalchemy.orm import sessionmaker
+
+app = FastAPI()
+e = create_engine("postgresql://localhost")
+Session = sessionmaker(bind=e)
+
+
+@app.get("/")
+async def read_root():
+    session = Session()
+    try:
+        now = session.execute("SELECT now()").scalar()
+        await asyncio.sleep(0.1)  # do some async work
+        return str(now)
+    finally:
+        session.close()
+

+

@app.get("/")
+async def read_root():
+    session = Session()
+    try:
+        now = session.execute("SELECT now()").scalar()
+        session.rollback()  # return the connection to avoid starvation
+        await asyncio.sleep(0.1)  # do some async work
+        return str(now)
+    finally:
+        session.close()
+

+

What about thread pool?

In summary, other than using raw SQL, the existing typical ORMs could not serve +asynchronous programming well enough. We need true asynchronous ORMs.

Asynchronous ORM Done Right¶

I would describe a proper asynchronous ORM as follows:

Don’t Starve.¶

@app.get("/")
+async def read_root():
+    async with db.acquire() as conn:  # }
+        async with conn.begin():      # } These two won't block the main thread
+            now = await db.scalar("SELECT now()")
+            await asyncio.sleep(0.1)  # do some async work
+            return str(now)
+

+

As the database connection pool is usually much smaller than the asynchronous server +concurrency, this kind of code caps the concurrency down to the DB pool level.
Taking a database connection from the pool for nothing is a waste of resource, +especially when the database pool is the shortest stave.
Database transactions should be kept short as much as possible. Because long-hanging +transactions may keep certain database locks, leading to performance issues or even +triggering a chain reaction of deadlocks.

Be explicit.¶

We could design the ORM model instances to be stateless, so that the users don’t have +to learn and worry about maintaining the state of the instances.
There shouldn’t be any “buffered operations” which users could “flush” with a single +statement once for all.
The user should just give direct one-off commands and the ORM executes them right away.
Also I think the convenience tooling should be well-balanced, the user doesn’t have to +guess or remember what an API means - for example, there’re more than one ways to load +a many-to-one relationship, I’d prefer to write the query by myself rather than trying +to remember what “join_without_n_plus_1()” means.

Be productive.¶

+ + +

+ + + +
+ This work is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License. +

+ +

Why Asynchronous ORM?
- When asyncio Helps
- How to Access Database
- Asynchronous ORM Done Right
  - Don’t Starve.
  - Be explicit.
  - Be productive.
  +
+

+ + +

+ +

+ + +

+ Add your language here. +

+ +

+ +

+ + + + + + + + + + + \ No newline at end of file diff --git a/docs/en/1.1b2/genindex.html b/docs/en/1.1b2/genindex.html new file mode 100644 index 0000000..270c3b2 --- /dev/null +++ b/docs/en/1.1b2/genindex.html @@ -0,0 +1 @@ +

genindex.html

\ No newline at end of file diff --git a/docs/en/1.1b2/how-to.html b/docs/en/1.1b2/how-to.html new file mode 100644 index 0000000..48a26c7 --- /dev/null +++ b/docs/en/1.1b2/how-to.html @@ -0,0 +1,286 @@ + + + + + + + + How-to Guides - GINO 1.1.0b2 documentation + + + + + + + + + + + +

+ +

+ + + + + +

+ + + +

+ + HOME + + + CREDITS + + +

Tutorials

How-to Guides

+ +

Explanation

Reference

+ +

How-to Guides¶

+ + +

+ + + +
+ This work is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License. +

+ +

How-to Guides

+ + +

+ Add your language here. +

+ +

+ +

+ + + + + + + + + + + \ No newline at end of file diff --git a/docs/en/1.1b2/how-to/alembic.html b/docs/en/1.1b2/how-to/alembic.html new file mode 100644 index 0000000..cbd5287 --- /dev/null +++ b/docs/en/1.1b2/how-to/alembic.html @@ -0,0 +1,297 @@ + + + + + + + + Use Alembic - GINO 1.1.0b2 documentation + + + + + + + + + + + +

+ +

+ + + + + + + +

+ + + +

+ + HOME + + + CREDITS + + +

Tutorials

How-to Guides

Explanation

Reference

+ +

Use Alembic¶

Alembic is a lightweight database migration tool for usage with the SQLAlchemy Database +Toolkit for Python. It’s also possible to use with GINO.

To add migrations to project first of all, add alembic as dependency:

$ pip install --user alembic
+

+

When you need to set up alembic for your project.

Prepare sample project. We will have a structure:

alembic_sample/
+    my_app/
+        models.py
+

+

Inside models.py define simple DB Model with GINO:

from gino import Gino
+
+db = Gino()
+
+class User(db.Model):
+    __tablename__ = 'users'
+
+    id = db.Column(db.Integer(), primary_key=True)
+    nickname = db.Column(db.Unicode(), default='noname')
+

+

Set up Alembic¶

This will need to be done only once. Go to the main folder of your project +alembic_sample and run:

$ alembic init alembic
+

+

sqlalchemy.url = postgres://{{username}}:{{password}}@{{address}}/{{db_name}}
+

+

Inside alembic/env.py:

from main_app.models import db
+

+

And change target_metadata = to:

target_metadata = db
+

+

That’s it. We finished setting up Alembic for a project.

Note

All alembic commands must be run always from the folder that contains the +alembic.ini file.

Create first migration revision¶

Same commands you must run each time when you make some changes in DB Models and want to +apply these changes to your DB Schema.

$ alembic revision -m "first migration" --autogenerate --head head
+

+

If you have any problems relative to package imports similar to this example:

File "alembic/env.py", line 7, in <module>
+    from main_app.models import db
+ModuleNotFoundError: No module named 'main_app'
+

+

Either install your project locally with pip install -e ., poetry install or +python setup.py develop, or add you package to PYTHONPATH, like this:

$ export PYTHONPATH=$PYTHONPATH:/full_path/to/alembic_sample
+

+

After the successful run of alembic revision in folder alembic/versions you will +see a file with new migration.

Apply migration on DB¶

Now time to apply migration to DB. It will create tables based on you DB Models.

$ alembic upgrade head
+

+

Great. Now you apply your first migration. Congratulations!

Next time, when you will make any changes in DB models just do:

$ alembic revision -m "your migration description" --autogenerate --head head
+

+

And

alembic upgrade head
+

+

Full documentation about how to work with Alembic migrations, downgrades and other +things - you can find in official docs https://alembic.sqlalchemy.org

+ + +

+ + + +
+ This work is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License. +

+ +

Use Alembic
+

+ + +

+ +

+ + +

+ Add your language here. +

+ +

+ +

+ + + + + + + + + + + \ No newline at end of file diff --git a/docs/en/1.1b2/how-to/bakery.html b/docs/en/1.1b2/how-to/bakery.html new file mode 100644 index 0000000..daad040 --- /dev/null +++ b/docs/en/1.1b2/how-to/bakery.html @@ -0,0 +1,403 @@ + + + + + + + + Bake Queries - GINO 1.1.0b2 documentation + + + + + + + + + + + +

+ +

+ + + + + + + +

+ + + +

+ + HOME + + + CREDITS + + +

Tutorials

How-to Guides

Explanation

Reference

+ +

Bake Queries¶

New in version 1.1.

Baked queries are used to boost execution performance for constantly-used queries. +Similar to the Baked Queries in SQLAlchemy, GINO could also cache the +object’s construction and string-compilation steps. Furthermore, GINO automatically +manages a prepared statement for each baked query in every active connection in the +pool. Executing baked queries is at least 40% faster than running normal queries, but +you need to bake them before creating the engine.

GINO provides two approaches for baked queries:

Low-level Bakery API
High-level Gino.bake() integration

Use Bakery with Bare Engine¶

First, we need a bakery:

import gino
+
+bakery = gino.Bakery()
+

+

Then, let’s bake some queries:

db_time = bakery.bake("SELECT now()")
+

+

Or queries with parameters:

user_query = bakery.bake("SELECT * FROM users WHERE id = :uid")
+

+

Let’s assume we have this users table defined in SQLAlchemy Core:

import sqlalchemy as sa
+
+metadata = sa.MetaData()
+user_table = sa.Table(
+    "users", metadata,
+    sa.Column("id", sa.Integer, primary_key=True),
+    sa.Column("name", sa.String),
+)
+

+

Now we can bake a similar query with SQLAlchemy Core:

user_query = bakery.bake(
+    sa.select([user_table]).where(user.c.id == sa.bindparam("uid"))
+)
+

+

These baked queries are usually global, and supposed to be shared across the +application. To run them, we need an engine with the bakery:

engine = await gino.create_engine("postgresql://localhost/", bakery=bakery)
+

+

By doing so, GINO will bake the queries in the bakery. As new connections are added to +the DB pool, the prepared statements are automatically created behind the scene.

To execute the baked queries, you could treat the BakedQuery +instances as if they are the queries themselves, for example:

now = await engine.scalar(db_time)
+

+

Pass in parameter values:

row = await engine.first(user_query, uid=123)
+

+

Use the `Gino` Integration¶

In a more common scenario, there will be a Gino instance, which has +usually a bind set - either explicitly or by the Web framework extensions:

from gino import Gino
+
+db = Gino()
+
+async def main():
+    async with db.with_bind("postgresql://localhost/"):
+        ...
+

+

A Bakery is automatically created in the db instance, and fed +to the engine implicitly. You can immediately start to bake queries without further +ado:

class User(db.Model):
+    __tablename__ = "users"
+
+    id = db.Column(db.Integer, primary_key=True)
+    name = db.Column(db.String)
+
+db_time = db.bake("SELECT now()")
+user_getter = db.bake(User.query.where(User.id == db.bindparam("uid")))
+

+

And the execution is also simplified with the same bind magic:

async def main():
+    async with db.with_bind("postgresql://localhost/"):
+        print(await db_time.scalar())
+
+        user: User = await user_getter.first(uid=1)
+        print(user.name)
+

+

To make things easier, you could even define the baked queries directly on the +model:

class User(db.Model):
+    __tablename__ = "users"
+
+    id = db.Column(db.Integer, primary_key=True)
+    name = db.Column(db.String)
+
+    @db.bake
+    def getter(cls):
+        return cls.query.where(cls.id == db.bindparam("uid"))
+
+    @classmethod
+    async def get(cls, uid):
+        return await cls.getter.one_or_none(uid=uid)
+

+

Here GINO treats the getter() as a declared_attr() with +with_table=True, therefore it takes one positional argument cls for the User +class.

How to customize loaders?¶

If possible, you could bake the additional execution options into the query:

user_getter = db.bake(
+    User.query.where(User.id == db.bindparam("uid")).execution_options(
+        loader=User.load(comment="Added by loader.")
+    )
+)
+

+

The bake() method accepts keyword arguments as execution +options to e.g. simplify the example above into:

user_getter = db.bake(
+    User.query.where(User.id == db.bindparam("uid")),
+    loader=User.load(comment="Added by loader."),
+)
+

+

If the query construction is complex, bake() could also be +used as a decorator:

@db.bake
+def user_getter():
+    return User.query.where(User.id == db.bindparam("uid")).execution_options(
+        loader=User.load(comment="Added by loader.")
+    )
+

+

Or with short execution options:

@db.bake(loader=User.load(comment="Added by loader."))
+def user_getter():
+    return User.query.where(User.id == db.bindparam("uid"))
+

+

Meanwhile, it is also possible to override the loader at runtime:

user: User = await user_getter.load(User).first(uid=1)
+print(user.name)  # no more comment on user!
+

+

Hint

This override won’t affect the baked query - it’s used only in this execution.

What APIs are available on `BakedQuery`?¶

BakedQuery is a GinoExecutor, so it inherited +all the APIs like all(), +first(), one(), +one_or_none(), scalar(), +status(), load(), +timeout(), etc.

GinoExecutor is actually the chained .gino helper API seen +usually in queries like this:

user = await User.query.where(User.id == 123).gino.first()
+

+

So a BakedQuery can be seen as a normal query with the .gino +suffix, plus it is directly executable.

See also

Please see API document of gino.bakery for more information.

I don’t want the prepared statements.¶

If you don’t need all the baked queries (m) to create prepared statements for all +the active database connections (n) in the beginning, you could set +prebake=False in the engine initialization to prevent the default initial +m x n prepare calls:

e = await gino.create_engine("postgresql://...", bakery=bakery, prebake=False)
+

+

Or if you’re using bind:

await db.set_bind("postgresql://...", prebake=False)
+

+

This is useful when you’re depending on db.gino.create_all() to create the tables, +because the prepared statements can only be created after the table creation.

The prepared statements will then be created and cached lazily on demand.

+ + +

+ + + +
+ This work is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License. +

+ +

Bake Queries
+

+ + +

+ +

+ + +

+ Add your language here. +

+ +

+ +

+ + + + + + + + + + + \ No newline at end of file diff --git a/docs/en/1.1b2/how-to/contributing.html b/docs/en/1.1b2/how-to/contributing.html new file mode 100644 index 0000000..532068b --- /dev/null +++ b/docs/en/1.1b2/how-to/contributing.html @@ -0,0 +1,360 @@ + + + + + + + + Contributing - GINO 1.1.0b2 documentation + + + + + + + + + + + +

+ +

+ + + + + + + +

+ + + +

+ + HOME + + + CREDITS + + +

Tutorials

How-to Guides

Explanation

Reference

+ +

Contributing¶

Contributions are welcome, and they are greatly appreciated! Every +little bit helps, and credit will always be given.

You can contribute in many ways:

Types of Contributions¶

Report Bugs¶

Report bugs at https://github.com/python-gino/gino/issues.

If you are reporting a bug, please include:

Your operating system name and version.
Any details about your local setup that might be helpful in troubleshooting.
Detailed steps to reproduce the bug.

Fix Bugs¶

Look through the GitHub issues for bugs. Anything tagged with “bug” +and “help wanted” is open to whoever wants to implement it.

Implement Features¶

Look through the GitHub issues for features. Anything tagged with “enhancement” +and “help wanted” is open to whoever wants to implement it.

Write Documentation¶

GINO could always use more documentation, whether as part of the +official GINO docs, in docstrings, or even on the web in blog posts, +articles, and such.

Submit Feedback¶

The best way to send feedback is to file an issue at https://github.com/python-gino/gino/issues.

If you are proposing a feature:

Explain in detail how it would work.
Keep the scope as narrow as possible, to make it easier to implement.
Remember that this is a volunteer-driven project, and that contributions +are welcome :)

Get Started!¶

Ready to contribute? Here’s how to set up gino for local development.

Fork the gino repo on GitHub.

Clone your fork locally:

$ git clone git@github.com:your_name_here/gino.git
+

+

Create a branch for local development:

$ cd gino/
+$ git checkout -b name-of-your-bugfix-or-feature
+

+

Now you can make your changes locally.

Create virtual environment. Example for virtualenvwrapper:
+
```
$ mkvirtualenv gino
+
```
+
+
Activate the environment and install requirements:
+
```
$ pip install -r requirements_dev.txt
+
```
+
+
When you’re done making changes, check that your changes pass syntax checks:
+
```
$ flake8 gino tests
+
```
+
+

7. And tests (including other Python versions with tox). +For tests you you will need running database server (see “Tips” section below for configuration details):

$ pytest tests
+$ tox
+

+

For docs run:
+
```
$ make docs
+
```
+
+

It will build and open up docs in your browser.

Commit your changes and push your branch to GitHub:

$ git add .
+$ git commit -m "Your detailed description of your changes."
+$ git push origin name-of-your-bugfix-or-feature
+

+

Submit a pull request through the GitHub website.

Pull Request Guidelines¶

Before you submit a pull request, check that it meets these guidelines:

The pull request should include tests.
If the pull request adds functionality, the docs should be updated. Put +your new functionality into a function with a docstring, and add the +feature to the list in README.rst.
The pull request should work for Python 3.5, 3.6, 3.7 and 3.8. Check +https://github.com/python-gino/gino/actions?query=event%3Apull_request +and make sure that the tests pass for all supported Python versions.

Tips¶

To run a subset of tests:

$ py.test -svx tests.test_gino
+

+

CREATE ROLE gino WITH LOGIN ENCRYPTED PASSWORD 'gino';
+CREATE DATABASE gino WITH OWNER = gino;
+

+

Then run the tests like so:

$ export DB_USER=gino DB_PASS=gino DB_NAME=gino
+$ py.test
+

+

Here is an example for db server in docker. Some tests require ssl so you will need to run postgres with ssl enabled. +Terminal 1 (server):

$ openssl req -new -text -passout pass:abcd -subj /CN=localhost -out server.req -keyout privkey.pem
+$ openssl rsa -in privkey.pem -passin pass:abcd -out server.key
+$ openssl req -x509 -in server.req -text -key server.key -out server.crt
+$ chmod 600 server.key
+$ docker run --name gino_db --rm -it -p 5433:5432 -v "$(pwd)/server.crt:/var/lib/postgresql/server.crt:ro" -v "$(pwd)/server.key:/var/lib/postgresql/server.key:ro" postgres:12-alpine -c ssl=on -c ssl_cert_file=/var/lib/postgresql/server.crt -c ssl_key_file=/var/lib/postgresql/server.key
+

+

Terminal 2 (client):

$ export DB_USER=gino DB_PASS=gino DB_NAME=gino DB_PORT=5433
+$ docker exec gino_db psql -U postgres -c "CREATE ROLE $DB_USER WITH LOGIN ENCRYPTED PASSWORD '$DB_PASS'"
+$ docker exec gino_db psql -U postgres -c "CREATE DATABASE $DB_NAME WITH OWNER = $DB_USER;"
+$ pytest tests/test_aiohttp.py
+

+

+ + +

+ + + +
+ This work is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License. +

+ +

Contributing
- Types of Contributions
  - Report Bugs
  - Fix Bugs
  - Implement Features
  - Write Documentation
  - Submit Feedback
  +
- Get Started!
- Pull Request Guidelines
- Tips
+

+ + +

+ +

+ + +

+ Add your language here. +

+ +

+ +

+ + + + + + + + + + + \ No newline at end of file diff --git a/docs/en/1.1b2/how-to/crud.html b/docs/en/1.1b2/how-to/crud.html new file mode 100644 index 0000000..44b0de7 --- /dev/null +++ b/docs/en/1.1b2/how-to/crud.html @@ -0,0 +1,195 @@ + + + + + + + + CRUD - GINO 1.1.0b2 documentation + + + + + + + + + + + +

+ +

+ + + + + + + +

+ + + +

+ + HOME + + + CREDITS + + +

Tutorials

How-to Guides

Explanation

Reference

+ +

CRUD¶

THIS IS A WIP

+ + +

+ + + +
+ This work is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License. +

+ +

CRUD

+ + +

+ Add your language here. +

+ +

+ +

+ + + + + + + + + + + \ No newline at end of file diff --git a/docs/en/1.1b2/how-to/faq.html b/docs/en/1.1b2/how-to/faq.html new file mode 100644 index 0000000..c6699e0 --- /dev/null +++ b/docs/en/1.1b2/how-to/faq.html @@ -0,0 +1,558 @@ + + + + + + + + Frequently Asked Questions - GINO 1.1.0b2 documentation + + + + + + + + + + + +

+ + +

Tutorials

How-to Guides

Explanation

Reference

+ +

Frequently Asked Questions¶

SQLAlchemy 1.4 supports asyncio, what will GINO be?¶

Contextual Connections (see Engine and Connection)
SQLAlchemy Core-based CRUD models
The GINO Loader system
Async MySQL support
Typing support ^NEW
Trio support ^NEW
Execution performance ^NEW

ORM or not ORM?¶

Can I use features of SQLAlchemy ORM?¶

SQLAlchemy has two parts:

SQLAlchemy Core
SQLAlchemy ORM

GINO is built on top of SQLAlchemy Core, so SQLAlchemy ORM won’t work in GINO.

How to join?¶

results = await User.join(Book).select().gino.all()
+

+

How to connect to database through SSL?¶

engine = await gino.create_engine(..., ssl=True)
+

+

What is aiocontextvars and what does it do?¶

If you are using Python 3.7, then aiocontextvars does nothing at all.

Note

This answer is for GINO 0.8 and later, please check earlier versions of +this documentation if you are using GINO 0.7.

How to define relationships?¶

How to define index with multiple columns?¶

class User(db.Model):
+    __tablename__ = 'users'
+
+    first_name = db.Column(db.Unicode())
+    last_name = db.Column(db.Unicode())
+
+    _name_idx = db.Index('index_on_name', 'first_name', 'last_name')
+

+

The _name_idx is not used.

Is there a django admin interface for GINO?¶

Not quite yet, please follow this discussion.

How to use multiple databases for different users on the fly?¶

GINO models are linked to a Gino instance, while +Gino has an optional property bind to hold a +GinoEngine instance. So when you are executing:

user = await User.get(request.user_id)
+

+

The bind is implicitly used to execute the query.

In order to use multiple databases, you would need multiple +GinoEngine instances. Here’s a full example using FastAPI with +lazy engine creation:

from asyncio import Future
+from contextvars import ContextVar
+
+from fastapi import FastAPI, Request
+from gino import create_engine
+from gino.ext.starlette import Gino
+
+engines = {}
+dbname = ContextVar("dbname")
+
+
+class ContextualGino(Gino):
+    @property
+    def bind(self):
+        e = engines.get(dbname.get(""))
+        if e and e.done():
+            return e.result()
+        else:
+            return self._bind
+
+    @bind.setter
+    def bind(self, val):
+        self._bind = val
+
+
+app = FastAPI()
+db = ContextualGino(app)
+
+
+@app.middleware("http")
+async def lazy_engines(request: Request, call_next):
+    name = request.query_params.get("db", "postgres")
+    fut = engines.get(name)
+    if fut is None:
+        fut = engines[name] = Future()
+        try:
+            engine = await create_engine("postgresql://localhost/" + name)
+        except Exception as e:
+            fut.set_exception(e)
+            del engines[name]
+            raise
+        else:
+            fut.set_result(engine)
+    await fut
+    dbname.set(name)
+    return await call_next(request)
+
+
+@app.get("/")
+async def get():
+    return dict(dbname=await db.scalar("SELECT current_database()"))
+

+

How to load complex query results?¶

The API doc of gino.loader explains the available loaders, and there’re a few +examples in Loaders and Relationship too.

Below is an example with a joined result to load both a GINO model and an integer at the +same time, using a TupleLoader with two sub-loaders - +ModelLoader and ColumnLoader:

import asyncio
+import random
+import string
+
+import gino
+from gino.loader import ColumnLoader
+
+db = gino.Gino()
+
+
+class User(db.Model):
+    __tablename__ = 'users'
+
+    id = db.Column(db.Integer(), primary_key=True)
+    name = db.Column(db.Unicode())
+
+
+class Visit(db.Model):
+    __tablename__ = 'visits'
+
+    id = db.Column(db.Integer(), primary_key=True)
+    time = db.Column(db.DateTime(), server_default='now()')
+    user_id = db.Column(db.ForeignKey('users.id'))
+
+
+async def main():
+    async with db.with_bind('postgresql://localhost/gino'):
+        await db.gino.create_all()
+
+        for i in range(random.randint(5, 10)):
+            u = await User.create(
+                name=''.join(random.choices(string.ascii_letters, k=10)))
+            for v in range(random.randint(10, 20)):
+                await Visit.create(user_id=u.id)
+
+        visits = db.func.count(Visit.id)
+        q = db.select([
+            User,
+            visits,
+        ]).select_from(
+            User.outerjoin(Visit)
+        ).group_by(
+            *User,
+        ).gino.load((User, ColumnLoader(visits)))
+        async with db.transaction():
+            async for user, visits in q.iterate():
+                print(user.name, visits)
+
+        await db.gino.drop_all()
+
+
+asyncio.run(main())
+

+

Be ware of the tuple in .gino.load((...)).

How to do bulk or batch insert / update?¶

For a simple example, take a model that has one field, “name.” In your application you +have a list of names you would like to add to the database:

new_names = ["Austin", "Ali", "Jeff", "Marissa"]
+

+

To quickly insert the names in one query, first construct a dict with the +{"model_key": "value"} format:

new_names_dict = [dict(name=new_name) for new_name in new_names]
+>> [{'name': 'Austin'}, {'name': 'Ali'}, {'name': 'Jeff'}, {'name': 'Marissa'}]
+

+

Finally, run an insert statement on the model:

await User.insert().gino.all(new_names_dict)
+

+

How to print the executed SQL?¶

GINO uses the same approach from SQLAlchemy: create_engine(..., echo=True). +(Or db.set_bind(..., echo=True)) Please see also here.

If you use any extension, you can also set that in config, by db_echo or DB_ECHO.

How to run `EXISTS` SQL?¶

await db.scalar(db.exists().where(User.email == email).select())
+

+

How to work with Alembic?¶

The fact that Gino is a MetaData is the +key to use Alembic. Just import and set target_metadata = db in Alembic env.py +will do. See Use Alembic for more details.

How to join the same table twice?¶

class User(db.Model):
+    __tablename__ = "users"
+
+    id = db.Column(db.Integer, primary_key=True)
+    parent_id = db.Column(db.ForeignKey("users.id"))
+
+Parent = User.alias()
+query = User.outerjoin(Parent, User.parent_id == Parent.id).select()
+users = await query.gino.load(User.load(parent=Parent)).all()
+

+

How to execute raw SQL with parameters?¶

Wrap the SQL with text(), and use keyword arguments:

query = db.text('SELECT * FROM users WHERE id = :id_val')
+row = await db.first(query, id_val=1)
+

+

You may even load the rows into model instances:

query = query.execution_options(loader=User)
+user = await db.first(query, id_val=1)
+

+

Gino engine is not initialized?¶

GINO models are linked to a Gino instance, while +Gino has an optional property bind to hold a +GinoEngine instance. So when you are executing:

user = await User.get(request.user_id)
+

+

The bind is implicitly used to execute the query. If bind is not set before +this, you’ll see this error:

gino.exceptions.UninitializedError: Gino engine is not initialized.
+

+

You could use either:

Call set_bind() or with_bind() to set the +bind on the Gino instance.
Use one of the Web framework extensions to set the bind for you in usually the server +start-up hook.

Use explicit bind for each execution, for example:

engine = await create_engine("...")
+# ...
+user = await User.get(request.user_id, bind=engine)
+

+

How can I do SQL xxxx in GINO?¶

Alternatively, you could always execute the raw SQL directly, see How to execute raw SQL with parameters? above.

+ + +

+ + + +
+ This work is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License. +

+ +

Frequently Asked Questions
+

+ + +

+ +

+ + +

+ Add your language here. +

+ +

+ +

+ + + + + + + + + + + \ No newline at end of file diff --git a/docs/en/1.1b2/how-to/json-props.html b/docs/en/1.1b2/how-to/json-props.html new file mode 100644 index 0000000..9277692 --- /dev/null +++ b/docs/en/1.1b2/how-to/json-props.html @@ -0,0 +1,376 @@ + + + + + + + + JSON Property - GINO 1.1.0b2 documentation + + + + + + + + + + + +

+ + +

Tutorials

How-to Guides

Explanation

Reference

+ +

JSON Property¶

GINO provides additional support to leverage native JSON type in the database as +flexible GINO model fields.

Quick Start¶

from gino import Gino
+from sqlalchemy.dialects.postgresql import JSONB
+
+db = Gino()
+
+class User(db.Model):
+    __tablename__ = "users"
+
+    id = db.Column(db.Integer, primary_key=True)
+    name = db.Column(db.String)
+    profile = db.Column(JSONB, nullable=False, server_default="{}")
+
+    age = db.IntegerProperty()
+    birthday = db.DateTimeProperty()
+

+

The age and birthday are JSON properties stored in the profile column. You +may use them the same way as a normal GINO model field:

u = await User.create(name="daisy", age=18)
+print(u.name, u.age)  # daisy 18
+

+

Note

profile is the default column name for all JSON properties in a model. If you +need a different column name for some JSON properties, you’ll need to specify +explicitly:

audit_profile = db.Column(JSON, nullable=False, server_default="{}")
+
+access_log = db.ArrayProperty(prop_name="audit_profile")
+abnormal_detected = db.BooleanProperty(prop_name="audit_profile")
+

+

Using JSON properties in queries is supported:

await User.query.where(User.age > 16).gino.all()
+

+

This is simply translated into a native JSON query like this:

SELECT users.id, users.name, users.profile
+FROM users
+WHERE CAST((users.profile ->> $1) AS INTEGER) > $2;  -- ('age', 16)
+

+

Datetime type is very much the same:

from datetime import datetime
+
+await User.query.where(User.birthday > datetime(1990, 1, 1)).gino.all()
+

+

And the generated SQL:

SELECT users.id, users.name, users.profile
+FROM users
+WHERE CAST((users.profile ->> $1) AS TIMESTAMP WITHOUT TIME ZONE) > $2
+-- ('birthday', datetime.datetime(1990, 1, 1, 0, 0))
+

+

Here’s a list of all the supported JSON properties:

+ ++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

JSON Property	Python type	JSON type	Database Type
`StringProperty`	`str`	`string`	`text`
`IntegerProperty`	`int`	`number`	`int`
`BooleanProperty`	`bool`	`boolean`	`boolean`
`DateTimeProperty`	`datetime`	`string`	`text`
`ObjectProperty`	`dict`	`object`	JSON
`ArrayProperty`	`list`	`array`	JSON

Hooks¶

JSON property provides 2 instance-level hooks to customize the data:

class User(db.Model):
+    __tablename__ = "users"
+
+    id = db.Column(db.Integer, primary_key=True)
+    profile = db.Column(JSONB, nullable=False, server_default="{}")
+
+    age = db.IntegerProperty()
+
+    @age.before_set
+    def age(self, val):
+        return val - 1
+
+    @age.after_get
+    def age(self, val):
+        return val + 1
+
+u = await User.create(name="daisy", age=18)
+print(u.name, u.profile, u.age)  # daisy {'age': 17} 18
+

+

And 1 class-level hook to customize the SQLAlchemy expression of the property:

class User(db.Model):
+    __tablename__ = "users"
+
+    id = db.Column(db.Integer, primary_key=True)
+    profile = db.Column(JSONB, nullable=False, server_default="{}")
+
+    height = db.JSONProperty()
+
+    @height.expression
+    def height(cls, exp):
+        return exp.cast(db.Float)  # CAST(profile -> 'height' AS FLOAT)
+

+

Create Index on JSON Properties¶

We’ll need to use declared_attr() to wait until the model class +is initialized. The rest is very much the same as defining a usual index:

class User(db.Model):
+    __tablename__ = "users"
+
+    id = db.Column(db.Integer, primary_key=True)
+    profile = db.Column(JSONB, nullable=False, server_default="{}")
+
+    age = db.IntegerProperty()
+
+    @db.declared_attr
+    def age_idx(cls):
+        return db.Index("age_idx", cls.age)
+

+

This will lead to the SQL below executed if you run db.gino.create_all():

CREATE INDEX age_idx ON users (CAST(profile ->> 'age' AS INTEGER));
+

+

Warning

Alembic doesn’t support auto-generating revisions for functional indexes yet. You’ll +need to manually edit the revision. Please follow this issue for updates.

+ + +

+ + + +
+ This work is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License. +

+ +

JSON Property
- Quick Start
- Hooks
- Create Index on JSON Properties
+

+ + +

+ +

+ + +

+ Add your language here. +

+ +

+ +

+ + + + + + + + + + + \ No newline at end of file diff --git a/docs/en/1.1b2/how-to/loaders.html b/docs/en/1.1b2/how-to/loaders.html new file mode 100644 index 0000000..d0b9433 --- /dev/null +++ b/docs/en/1.1b2/how-to/loaders.html @@ -0,0 +1,639 @@ + + + + + + + + Loaders and Relationship - GINO 1.1.0b2 documentation + + + + + + + + + + + +

+ + +

Tutorials

How-to Guides

Explanation

Reference

+ +

Loaders and Relationship¶

Loaders are used to load database row results into objects.

Model Loader¶

query = db.select([User])
+rows = await query.gino.all()
+

+

In order to load rows into User objects, you can provide an execution +option loader with a new ModelLoader instance:

from gino.loader import ModelLoader
+
+query = db.select([User])
+query = query.execution_options(loader=ModelLoader(User))
+users = await query.gino.all()
+

+

The ModelLoader would then load each database row into a +User object. As this is frequently used, GINO made it a shortcut:

query = db.select([User])
+query = query.execution_options(loader=User.load())
+users = await query.gino.all()
+

+

And another shortcut:

query = db.select([User])
+query = query.execution_options(loader=User)
+users = await query.gino.all()
+

+

Tip

User as loader is transformed into ModelLoader(User) by +Loader.get(), explained later in “Loader +Expression”.

And again:

query = db.select([User])
+users = await query.gino.load(User).all()
+

+

This is identical to the normal CRUD query:

users = await User.query.gino.all()
+

+

Loader Expression¶

Here is an example using all loaders at once:

uid, user, sep, cols = await db.select([User]).gino.load(
+    (
+        User.id,
+        User,
+        '|',
+        lambda row, ctx: len(row),
+    )
+).first()
+

+

now = db.Column('time', db.DateTime())
+result = await db.first(db.text(
+    'SELECT now() AT TIME ZONE \'UTC\''
+).columns(
+    now,
+).gino.load(
+    ('now:', now)
+).query)
+print(*result)  # now: 2018-04-08 08:23:02.431847
+

+

Tip

For a complex loader expression, the same row is given to all loaders, so +it doesn’t matter User.id is already used before the model loader.

At last, if none of the above types matches a Loader Expression, it will be +treated as is. Like the '|' separator, it will show up as the third item +in every result returned by the query.

Many-to-One Relationship¶

class Parent(db.Model):
+    __tablename__ = 'parents'
+    id = db.Column(db.Integer, primary_key=True)
+
+class Child(db.Model):
+    __tablename__ = 'children'
+    id = db.Column(db.Integer, primary_key=True)
+    parent_id = db.Column(db.Integer, db.ForeignKey('parents.id'))
+

+

So every child has a single parent (or no parent at all), while one parent may +have multiple children. GINO provides an easy way to load children with their +parents:

async for child in Child.load(parent=Parent).gino.iterate():
+    print(f'Parent of {child.id} is {child.parent.id}')
+

+

async for child in Child.load(parent=Parent).query.gino.iterate():
+    print(f'Parent of {child.id} is {child.parent.id}')
+

+

Warning

If multiple children references the same parent, then each child owns a +unique parent instance with identical values.

Tip

class Child(db.Model):
+    __tablename__ = 'children'
+    id = db.Column(db.Integer, primary_key=True)
+    parent_id = db.Column(db.Integer, db.ForeignKey('parents.id'))
+    _parent = None
+
+    @property
+    def parent(self):
+        return self._parent
+
+    @parent.setter
+    def parent(self, value):
+        self._parent = value
+

+

loader = Child.load(parent=Parent.on(Child.parent_id == Parent.id))
+async for child in loader.query.gino.iterate():
+    print(f'Parent of {child.id} is {child.parent.id}')
+

+

And subloaders can be nested:

subloader = Child.load(parent=Parent.on(Child.parent_id == Parent.id))
+loader = Grandson.load(parent=subloader.on(Grandson.parent_id == Child.id))
+

+

By now, GINO supports only loading many-to-one joined query. To modify a +relationship, just modify the reference column values.

Self Referencing¶

Warning

Experimental feature.

Self referencing is usually used to create a tree-like structure. For example:

class Category(db.Model):
+    __tablename__ = 'categories'
+    id = db.Column(db.Integer, primary_key=True)
+    parent_id = db.Column(db.Integer, db.ForeignKey('categories.id'))
+

+

In order to load leaf categories with their parents, an alias is needed:

Parent = Category.alias()
+

+

Then the query would be something like this:

parents = db.select([Category.parent_id])
+query = Category.load(parent=Parent.on(
+    Category.parent_id == Parent.id
+)).where(
+    ~Category.id.in_(db.select([Category.alias().parent_id]))
+)
+async for c in query.gino.iterate():
+    print(f'Leaf: {c.id}, Parent: {c.parent.id}')
+

+

The generated SQL looks like this:

SELECT categories.id, categories.parent_id, categories_1.id, categories_1.parent_id
+  FROM categories LEFT OUTER JOIN categories AS categories_1
+    ON categories.parent_id = categories_1.id
+ WHERE categories.id NOT IN (
+           SELECT categories_2.parent_id
+             FROM categories AS categories_2
+       )
+

+

Other Relationships¶

class Parent(db.Model):
+    __tablename__ = 'parents'
+    id = db.Column(db.Integer, primary_key=True)
+
+    def __init__(self, **kw):
+        super().__init__(**kw)
+        self._children = set()
+
+    @property
+    def children(self):
+        return self._children
+
+    @children.setter
+    def add_child(self, child):
+        self._children.add(child)
+
+
+class Child(db.Model):
+    __tablename__ = 'children'
+    id = db.Column(db.Integer, primary_key=True)
+    parent_id = db.Column(db.Integer, db.ForeignKey('parents.id'))
+
+
+query = Child.outerjoin(Parent).select()
+parents = await query.gino.load(
+    Parent.distinct(Parent.id).load(add_child=Child)).all()
+

+

Distinct loaders can be nested to load hierarchical data, but it cannot be used +as a query builder to automatically generate queries.

class Parent(db.Model):
+    __tablename__ = 'parents'
+    id = db.Column(db.Integer, primary_key=True)
+
+    def __init__(self, **kw):
+        super().__init__(**kw)
+        self._child = None
+
+    @property
+    def child(self):
+        return self._child
+
+    @child.setter
+    def child(self, child):
+        self._child = child
+
+
+class Child(db.Model):
+    __tablename__ = 'children'
+    id = db.Column(db.Integer, primary_key=True)
+    parent_id = db.Column(db.Integer, db.ForeignKey('parents.id'))
+
+
+query = Child.outerjoin(Parent).select()
+parents = await query.gino.load(
+    Parent.distinct(Parent.id).load(child=Child.distinct(Child.id))).all()
+

+

Similarly, you can build many-to-many relationships in the same way:

class Parent(db.Model):
+    __tablename__ = 'parents'
+    id = db.Column(db.Integer, primary_key=True)
+
+    def __init__(self, **kw):
+        super().__init__(**kw)
+        self._children = set()
+
+    @property
+    def children(self):
+        return self._children
+
+    def add_child(self, child):
+        self._children.add(child)
+        child._parents.add(self)
+
+
+class Child(db.Model):
+    __tablename__ = 'children'
+    id = db.Column(db.Integer, primary_key=True)
+
+    def __init__(self, **kw):
+        super().__init__(**kw)
+        self._parents = set()
+
+    @property
+    def parents(self):
+        return self._parents
+
+
+class ParentXChild(db.Model):
+    __tablename__ = 'parents_x_children'
+
+    parent_id = db.Column(db.Integer, db.ForeignKey('parents.id'))
+    child_id = db.Column(db.Integer, db.ForeignKey('children.id'))
+
+
+query = Parent.outerjoin(ParentXChild).outerjoin(Child).select()
+parents = await query.gino.load(
+    Parent.distinct(Parent.id).load(add_child=Child.distinct(Child.id))).all()
+

+

Likewise, there is for now no way to modify the relationships automatically, +you’ll have to manually create, delete or modify ParentXChild instances.

Advanced Usage of Loaders¶

import asyncio
+import random
+import string
+
+import gino
+from gino.loader import ColumnLoader
+
+db = gino.Gino()
+
+
+class User(db.Model):
+    __tablename__ = 'users'
+
+    id = db.Column(db.Integer(), primary_key=True)
+    name = db.Column(db.Unicode())
+
+
+class Visit(db.Model):
+    __tablename__ = 'visits'
+
+    id = db.Column(db.Integer(), primary_key=True)
+    time = db.Column(db.DateTime(), server_default='now()')
+    user_id = db.Column(db.ForeignKey('users.id'))
+
+
+async def main():
+    async with db.with_bind('postgresql://localhost/gino'):
+        await db.gino.create_all()
+
+        for i in range(random.randint(5, 10)):
+            u = await User.create(
+                name=''.join(random.choices(string.ascii_letters, k=10)))
+            for v in range(random.randint(10, 20)):
+                await Visit.create(user_id=u.id)
+
+        visits = db.func.count(Visit.id)
+        q = db.select([
+            User,
+            visits,
+        ]).select_from(
+            User.outerjoin(Visit)
+        ).group_by(
+            *User,
+        ).gino.load((User, ColumnLoader(visits)))
+        async with db.transaction():
+            async for user, visits in q.iterate():
+                print(user.name, visits)
+
+        await db.gino.drop_all()
+
+
+asyncio.run(main())
+

+

Using alias to get ID-ascending pairs from the same table:

ua1 = User.alias()
+ua2 = User.alias()
+join_query = select([ua1, ua2]).where(ua1.id < ua2.id)
+loader = ua1.load('id'), ua2.load('id')
+result = await join_query.gino.load(loader).all()
+print(result)  # e.g. [(1, 2), (1, 3), (2, 3)]
+

+

Potentially there could be a lot of different use cases of loaders. We’ll add +more inspiration here in the future.

+ + +

+ + + +
+ This work is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License. +

+ +

Loaders and Relationship
+

+ + +

+ +

+ + +

+ Add your language here. +

+ +

+ +

+ + + + + + + + + + + \ No newline at end of file diff --git a/docs/en/1.1b2/how-to/pool.html b/docs/en/1.1b2/how-to/pool.html new file mode 100644 index 0000000..436c5ff --- /dev/null +++ b/docs/en/1.1b2/how-to/pool.html @@ -0,0 +1,217 @@ + + + + + + + + Connection Pool - GINO 1.1.0b2 documentation + + + + + + + + + + + +

+ + +

Tutorials

How-to Guides

Explanation

Reference

+ +

Connection Pool¶

To use non-default pools in raw GINO:

from gino.dialects.asyncpg import NullPool
+create_engine('postgresql://...', pool_class=NullPool)
+

+

To use non-default pools in extensions (taking Sanic as an example):

from gino.dialects.asyncpg import NullPool
+from gino.ext.sanic import Gino
+
+app = sanic.Sanic()
+app.config.DB_HOST = 'localhost'
+app.config.DB_KWARGS = dict(
+    pool_class=NullPool,
+)
+db = Gino()
+db.init_app(app)
+

+

+ + +

+ + + +
+ This work is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License. +

+ +

Connection Pool

+ + +

+ Add your language here. +

+ +

+ +

+ + + + + + + + + + + \ No newline at end of file diff --git a/docs/en/1.1b2/how-to/schema.html b/docs/en/1.1b2/how-to/schema.html new file mode 100644 index 0000000..5c618df --- /dev/null +++ b/docs/en/1.1b2/how-to/schema.html @@ -0,0 +1,419 @@ + + + + + + + + Schema Declaration - GINO 1.1.0b2 documentation + + + + + + + + + + + +

+ + +

Tutorials

How-to Guides

Explanation

Reference

+ +

Schema Declaration¶

There are 3 ways to declare your database schema to be used with GINO. Because +GINO is built on top of SQLAlchemy core, either way you are actually declaring +SQLAlchemy Table.

GINO Engine¶

For example, the table declaration is the same as SQLAlchemy core tutorial:

from sqlalchemy import Table, Column, Integer, String, MetaData, ForeignKey
+
+metadata = MetaData()
+
+users = Table(
+    'users', metadata,
+
+    Column('id', Integer, primary_key=True),
+    Column('name', String),
+    Column('fullname', String),
+)
+
+addresses = Table(
+    'addresses', metadata,
+
+    Column('id', Integer, primary_key=True),
+    Column('user_id', None, ForeignKey('users.id')),
+    Column('email_address', String, nullable=False)
+)
+

+

Note

import gino
+from gino.schema import GinoSchemaVisitor
+
+async def main():
+    engine = await gino.create_engine('postgresql://...')
+    await GinoSchemaVisitor(metadata).create_all(engine)
+

+

Then, construct queries, in SQLAlchemy core too:

ins = users.insert().values(name='jack', fullname='Jack Jones')
+

+

So far, everything is still in SQLAlchemy. Now let’s get connected and execute +the insert:

async def main():
+    engine = await gino.create_engine('postgresql://localhost/gino')
+    conn = await engine.acquire()
+    await conn.status(ins)
+    print(await conn.all(users.select()))
+    # Outputs: [(1, 'jack', 'Jack Jones')]
+

+

all() returns a list of +RowProxy
first() returns one +RowProxy, or None
one() returns one +RowProxy
one_or_none() returns one +RowProxy, or None
scalar() returns a single value, or +None
iterate() returns an asynchronous iterator +which yields RowProxy

Please go to their API for more information.

GINO Core¶

It delegates most public types you can access on sqlalchemy
It works with both normal SQLAlchemy engine and asynchronous GINO engine
It exposes all query APIs on GinoConnection level
It injects two gino extensions on SQLAlchemy query clauses and schema +items, allowing short inline execution like users.select().gino.all()
It is also the entry for the third scenario, see later

Then we can achieve previous scenario with less code like this:

from gino import Gino
+
+db = Gino()
+
+users = db.Table(
+    'users', db,
+
+    db.Column('id', db.Integer, primary_key=True),
+    db.Column('name', db.String),
+    db.Column('fullname', db.String),
+)
+
+addresses = db.Table(
+    'addresses', db,
+
+    db.Column('id', db.Integer, primary_key=True),
+    db.Column('user_id', None, db.ForeignKey('users.id')),
+    db.Column('email_address', db.String, nullable=False)
+)
+
+async def main():
+    async with db.with_bind('postgresql://localhost/gino'):
+        await db.gino.create_all()
+        await users.insert().values(
+            name='jack',
+            fullname='Jack Jones',
+        ).gino.status()
+        print(await users.select().gino.all())
+        # Outputs: [(1, 'jack', 'Jack Jones')]
+

+

Tip

GINO ORM¶

from gino import Gino
+
+db = Gino()
+
+
+class User(db.Model):
+    __tablename__ = 'users'
+
+    id = db.Column(db.Integer, primary_key=True)
+    name = db.Column(db.String)
+    fullname = db.Column(db.String)
+
+
+class Address(db.Model):
+    __tablename__ = 'addresses'
+
+    id = db.Column(db.Integer, primary_key=True)
+    user_id = db.Column(None, db.ForeignKey('users.id'))
+    email_address = db.Column(db.String, nullable=False)
+
+
+async def main():
+    async with db.with_bind('postgresql://localhost/gino'):
+        await db.gino.create_all()
+        await User.create(name='jack', fullname='Jack Jones')
+        print(await User.query.gino.all())
+        # Outputs: [<User object at 0x10a8ba860>]
+

+

Important

The __tablename__ is a mandatory field to define a concrete model.

Note

Tip

db.Model is a dynamically created parent class for your models. It is +associated with the db on initialization, therefore the table is put in +the very db when you declare your model class.

After all, GinoEngine is always in use. Next let’s dig +more into it.

+ + +

+ + + +
+ This work is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License. +

+ +

Schema Declaration
- GINO Engine
- GINO Core
- GINO ORM
+

+ + +

+ +

+ + +

+ Add your language here. +

+ +

+ +

+ + + + + + + + + + + \ No newline at end of file diff --git a/docs/en/1.1b2/how-to/transaction.html b/docs/en/1.1b2/how-to/transaction.html new file mode 100644 index 0000000..cf4e60e --- /dev/null +++ b/docs/en/1.1b2/how-to/transaction.html @@ -0,0 +1,303 @@ + + + + + + + + Transaction - GINO 1.1.0b2 documentation + + + + + + + + + + + +

+ +

+ + + + + + + +

+ + + +

+ + HOME + + + CREDITS + + +

Tutorials

How-to Guides

Explanation

Reference

+ +

Transaction¶

Basic usage¶

Transactions belong to GinoConnection. The most common +way to use transactions is through an async with statement:

async with connection.transaction() as tx:
+    await connection.status('INSERT INTO mytable VALUES(1, 2, 3)')
+

+

GINO provides two convenient shortcuts to end the transaction early:

Transactions can also be started on a GinoEngine:

async with engine.transaction() as tx:
+    await engine.status('INSERT INTO mytable VALUES(1, 2, 3)')
+

+

Important

Similarly, if your Gino instance has a bind, you may also do +the same on it:

async with db.transaction() as tx:
+    await db.status('INSERT INTO mytable VALUES(1, 2, 3)')
+

+

Nested Transactions¶

Transactions can be nested, nested transaction will create a savepoint as for +now on asyncpg. A similar example from asyncpg doc:

async with connection.transaction() as tx1:
+    await connection.status('CREATE TABLE mytab (a int)')
+
+    # Create a nested transaction:
+    async with connection.transaction() as tx2:
+        await connection.status('INSERT INTO mytab (a) VALUES (1), (2)')
+        # Rollback the nested transaction:
+        tx2.raise_rollback()
+
+    # Because the nested transaction was rolled back, there
+    # will be nothing in `mytab`.
+    assert await connection.all('SELECT a FROM mytab') == []
+

+

Because of the default reusing behavior, transactions on engine or db +follows the same nesting rules. Please see +GinoTransaction for more information.

Manual Control¶

Other than using async with, you can also manually control the +transaction:

tx = await connection.transaction()
+try:
+    await db.status('INSERT INTO mytable VALUES(1, 2, 3)')
+    await tx.commit()
+except Exception:
+    await tx.rollback()
+    raise
+

+

You can’t use raise_commit() or +raise_rollback() here, similarly it is +prohibited to use commit() and +rollback() in an async with block.

+ + +

+ + + +
+ This work is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License. +

+ +

Transaction
- Basic usage
- Nested Transactions
- Manual Control
+

+ + +

+ +

+ + +

+ Add your language here. +

+ +

+ +

+ + + + + + + + + + + \ No newline at end of file diff --git a/docs/en/1.1b2/index.html b/docs/en/1.1b2/index.html new file mode 100644 index 0000000..89527b2 --- /dev/null +++ b/docs/en/1.1b2/index.html @@ -0,0 +1,231 @@ + + + + + + + + Welcome to GINO’s documentation! - GINO 1.1.0b2 documentation + + + + + + + + + + + +

+ +

+ + + +

+ + HOME + + + CREDITS + + +

Tutorials

How-to Guides

Explanation

Reference

+ +

Welcome to GINO’s documentation!¶

GINO - GINO Is Not ORM - is a lightweight asynchronous ORM built on top of +SQLAlchemy core for Python asyncio. Now (early 2020) GINO supports only one +dialect asyncpg.

Tutorials
+
Lessons for the newcomer to get started
+
How-to Guides
+
Solve specific problems by steps
+
Explanation
+
Explains the background and context
+
Reference
+
Describes the software as it is
+

Useful Links¶

Source Code
+
https://github.com/python-gino/gino
+
Community
+
https://gitter.im/python-gino/Lobby
+
BSD license
+
GINO is free software
+
Download
+
Download GINO from PyPI
+

Sections by Divio.

+ + +

+ + + +
+ This work is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License. +

+ +

+ + +

+ Add your language here. +

+ +

+ +

+ + + + + + + + + + + \ No newline at end of file diff --git a/docs/en/1.1b2/objects.inv b/docs/en/1.1b2/objects.inv new file mode 100644 index 0000000..fc6c595 Binary files /dev/null and b/docs/en/1.1b2/objects.inv differ diff --git a/docs/en/1.1b2/py-modindex.html b/docs/en/1.1b2/py-modindex.html new file mode 100644 index 0000000..18dcbf9 --- /dev/null +++ b/docs/en/1.1b2/py-modindex.html @@ -0,0 +1 @@ +

domainindex.html

\ No newline at end of file diff --git a/docs/en/1.1b2/reference.html b/docs/en/1.1b2/reference.html new file mode 100644 index 0000000..b2c81d6 --- /dev/null +++ b/docs/en/1.1b2/reference.html @@ -0,0 +1,336 @@ + + + + + + + + Reference - GINO 1.1.0b2 documentation + + + + + + + + + + + +

+ +

+ + + + + +

+ + + +

+ + HOME + + + CREDITS + + +

Tutorials

How-to Guides

Explanation

Reference

Reference
- API Reference
- Extensions
- History
+
API Reference
Extensions
History

+ +

Reference¶

API Reference
- gino package
  - Subpackages
    - gino.dialects package
      - Submodules
        +
        gino.dialects.aiomysql module
        +
        gino.dialects.asyncpg module
        +
        gino.dialects.base module
        +
        +
      - Module contents
      +
    - gino.ext package
      - Module contents
      +
    +
  - Submodules
    +
  - Module contents
  +
+
Extensions
- Sanic Support
  - Work with Sanic
  - Sanic Support
  +
- Starlette Support
  - Work with Starlette
  - Configuration
  - Lazy Connection
  +
- Tornado Support
+
History
- GINO 1.1
  - 1.1.0 (pending)
  +
- GINO 1.0
  +
- GINO 0.8
  - Migrating to GINO 0.8
    - 1. contextvars
    - 2. none_as_none
    +
  - 0.8.7 (2020-04-19)
  - 0.8.6 (2020-02-10)
  - 0.8.5 (2019-11-19)
  - 0.8.4 (2019-11-09)
  - 0.8.3 (2019-06-06)
  - 0.8.2 (2019-03-07)
  - 0.8.1 (2018-12-08)
  - 0.8.0 (2018-10-16)
  +
- GINO 0.7
  +
- GINO 0.6
  - Migrating to GINO 0.6
    - 1. Task Local
    - 2. Engine
    - 3. GinoConnection
    - 4. Query API
    - 5. Transaction
    +
  - 0.6.6 (2018-05-18)
  - 0.6.5 (2018-04-18)
  - 0.6.4 (2018-04-16)
  - 0.6.3 (2018-04-08)
  - 0.6.2 (2018-03-24)
  - 0.6.1 (2018-03-18)
  - 0.6.0 (2018-03-14)
  +
- GINO 0.5
  +
- Early Development Releases
  +
+

+ + +

+ + + +
+ This work is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License. +

+ +

Reference

+ + +

+ Add your language here. +

+ +

+ +

+ + + + + + + + + + + \ No newline at end of file diff --git a/docs/en/1.1b2/reference/api.html b/docs/en/1.1b2/reference/api.html new file mode 100644 index 0000000..12c2124 --- /dev/null +++ b/docs/en/1.1b2/reference/api.html @@ -0,0 +1,242 @@ + + + + + + + + API Reference - GINO 1.1.0b2 documentation + + + + + + + + + + + +

+ +

+ + + + + + + +

+ + + +

+ + HOME + + + CREDITS + + +

Tutorials

How-to Guides

Explanation

Reference

Reference
- API Reference
- Extensions
- History
+
API Reference
- gino package
+
Extensions
History

+ +

API Reference¶

+ +

+ + +

+ + + +
+ This work is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License. +

+ +

API Reference

+ + +

+ Add your language here. +

+ +

+ +

+ + + + + + + + + + + \ No newline at end of file diff --git a/docs/en/1.1b2/reference/api/gino.aiocontextvars.html b/docs/en/1.1b2/reference/api/gino.aiocontextvars.html new file mode 100644 index 0000000..3d02f85 --- /dev/null +++ b/docs/en/1.1b2/reference/api/gino.aiocontextvars.html @@ -0,0 +1,216 @@ + + + + + + + + gino.aiocontextvars module - GINO 1.1.0b2 documentation + + + + + + + + + + + +

+ + +

Tutorials

How-to Guides

Explanation

Reference

Reference
- API Reference
- Extensions
- History
+
API Reference
- gino package
+
Extensions
History

+ +

gino.aiocontextvars module¶

+gino.aiocontextvars.patch_asyncio()¶

Patches asyncio to support contextvars.

This is automatically called when gino is imported. If Python version is 3.7 +or greater, this function is a no-op.

+ +

+ + +

+ + + +
+ This work is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License. +

+ +

gino.aiocontextvars module

+ + +

+ Add your language here. +

+ +

+ +

+ + + + + + + + + + + \ No newline at end of file diff --git a/docs/en/1.1b2/reference/api/gino.api.html b/docs/en/1.1b2/reference/api/gino.api.html new file mode 100644 index 0000000..b54603f --- /dev/null +++ b/docs/en/1.1b2/reference/api/gino.api.html @@ -0,0 +1,621 @@ + + + + + + + + gino.api module - GINO 1.1.0b2 documentation + + + + + + + + + + + +

+ + +

Tutorials

How-to Guides

Explanation

Reference

Reference
- API Reference
- Extensions
- History
+
API Reference
- gino package
+
Extensions
History

+ +

gino.api module¶

+class gino.api.Gino(bind=None, model_classes=None, query_ext=True, schema_ext=True, ext=True, **kwargs)¶

Bases: sqlalchemy.sql.schema.MetaData

All-in-one API class of GINO, providing several shortcuts.

For convenience, Gino instance delegated all properties publicly +exposed by sqlalchemy, so that you can define tables / models +without importing sqlalchemy:

id = db.Column(db.BigInteger(), primary_key=True)
+

+

Similar to MetaData, a Gino object +can bind to a GinoEngine instance, hereby allowing +“implicit execution” through the gino +extension on Executable or +SchemaItem constructs:

await User.query.gino.first()
+await db.gino.create_all()
+

+

Differently, GINO encourages the use of implicit execution and manages +transactional context correctly.

Binding to a connection object is not supported.

with_bind() returning an asynchronous context manager:

async with db.with_bind('postgresql://...') as engine:
+

+

set_bind() and pop_bind():

engine = await db.set_bind('postgresql://...')
+await db.pop_bind().close()
+

+

Directly await on Gino instance:

db = await gino.Gino('postgresql://...')
+await db.pop_bind().close()
+

+

Note

SQLAlchemy allows creating the engine by:

metadata.bind = 'postgresql://...'
+

+

While in GINO this only sets a string to bind, because +creating an engine requires await, which is exactly what +set_bind() does.

At last, Gino delegates all query APIs on the bound +GinoEngine.

+property Model¶: Declarative base class for models, subclass of +gino.declarative.Model. Defining subclasses of this class will +result new tables added to this Gino metadata.
+

+ +

+acquire(*args, **kwargs)¶: A delegate of GinoEngine.acquire().
+

+ +

+async all(clause, *multiparams, **params)¶: A delegate of GinoEngine.all().
+

+ +

+bake(func_or_elem=None, **execution_options)¶: A delegate of Bakery.bake().
+
+
New in version 1.1.
+
+

+ +

+property bakery¶: The bundled Bakery instance.
+
+
New in version 1.1.
+
+

+ +

+property bind¶

An GinoEngine to which this Gino is bound.

+ +

+compile(elem, *multiparams, **params)¶: A delegate of GinoEngine.compile().
+

+ +

+async first(clause, *multiparams, **params)¶: A delegate of GinoEngine.first().
+

+ +

+iterate(clause, *multiparams, **params)¶: A delegate of GinoEngine.iterate().
+

+ +

+model_base_classes = (<class 'gino.crud.CRUDModel'>,)¶

Overridable default model classes to build the Model.

Default is (CRUDModel, ).

+ +

+no_delegate = {'create_engine', 'engine_from_config'}¶: A set of symbols from sqlalchemy which is not delegated by +Gino.
+

+ +

+async one(clause, *multiparams, **params)¶: A delegate of GinoEngine.one().
+

+ +

+async one_or_none(clause, *multiparams, **params)¶: A delegate of GinoEngine.one_or_none().
+

+ +

+pop_bind()¶

Unbind self, and return the bound engine.

This is usually used in a chained call to close the engine:

await db.pop_bind().close()
+

+

Returns: GinoEngine or None if self is not bound.
+

+ +

+query_executor¶

The overridable gino extension class on +Executable.

This class will be set as the getter method of the property gino on +Executable and its subclasses, if +ext and query_ext arguments are both True. Default is +GinoExecutor.

alias of GinoExecutor

+ +

+async scalar(clause, *multiparams, **params)¶: A delegate of GinoEngine.scalar().
+

+ +

+schema_visitor¶: alias of gino.schema.GinoSchemaVisitor
+

+ +

+async set_bind(bind, loop=None, **kwargs)¶

Bind self to the given GinoEngine and return it.

If the given bind is a string or +URL, all arguments will be sent to +create_engine() to create a new engine, and return it.

Returns: GinoEngine
+

+ +

+async status(clause, *multiparams, **params)¶: A delegate of GinoEngine.status().
+

+ +

+transaction(*args, **kwargs)¶: A delegate of GinoEngine.transaction().
+

+ +

+with_bind(bind, loop=None, **kwargs)¶

Shortcut for set_bind() and pop_bind() plus closing engine.

This method accepts the same arguments of +create_engine(). This allows inline creating an engine and +binding self on enter, and unbinding self and closing the engine on +exit:

async with db.with_bind('postgresql://...') as engine:
+    # play with engine
+

+

Returns: An asynchronous context manager.
+

+ +

+class gino.api.GinoExecutor(query)¶

Bases: object

The default gino extension on +Executable constructs for implicit +execution.

Instances of this class are created when visiting the gino property of +Executable instances (also referred as +queries or clause elements), for example:

await User.query.gino.first()
+

+

Note

Executable clause elements that are completely irrelevant with any +table - for example db.select([db.text('now()')]) - has no +metadata, hence no engine. Therefore, this will always fail:

await db.select([db.text('now()')]).gino.scalar()
+

+

You should use conn.scalar(), +engine.scalar() or even +db.scalar() in this case.

+async all(*multiparams, **params)¶: Returns engine.all() with this query +as the first argument, and other arguments followed, where engine +is the GinoEngine to which the metadata +(Gino) is bound, while metadata is found in this query.
+

+ +

+execution_options(**options)¶

Set execution options to this query in a chaining call.

Read execution_options() for more +information.

Parameters: options – Multiple execution options.
+

New in version 1.1.

+ +

+async first(*multiparams, **params)¶: Returns engine.first() with this +query as the first argument, and other arguments followed, where +engine is the GinoEngine to which the metadata +(Gino) is bound, while metadata is found in this query.
+

+ +

+iterate(*multiparams, **params)¶: Returns engine.iterate() with this +query as the first argument, and other arguments followed, where +engine is the GinoEngine to which the metadata +(Gino) is bound, while metadata is found in this query.
+

+ +

+load(value)¶

Shortcut to set execution option loader in a chaining call.

For example to load Book instances with their authors:

query = Book.join(User).select()
+books = await query.gino.load(Book.load(author=User)).all()
+

+

Read execution_options() for more +information.

+ +

+model(model)¶

Shortcut to set execution option model in a chaining call.

Read execution_options() for more +information.

+ +

+async one(*multiparams, **params)¶: Returns engine.one() with this query +as the first argument, and other arguments followed, where engine +is the GinoEngine to which the metadata +(Gino) is bound, while metadata is found in this query.
+

+ +

+async one_or_none(*multiparams, **params)¶: Returns engine.one_or_none() +with this query as the first argument, and other arguments followed, +where engine is the GinoEngine to which the +metadata (Gino) is bound, while metadata is found in this +query.
+

+ +

+property query¶

Get back the chained Executable.

In a chained query calls, occasionally the previous query clause is +needed after a .gino. chain, you can use .query. to resume the +chain back. For example:

await User.query.gino.model(FOUser).query.where(...).gino.all()
+

+

+ +

+return_model(switch)¶

Shortcut to set execution option return_model in a chaining call.

Read execution_options() for more +information.

+ +

+async scalar(*multiparams, **params)¶: Returns engine.scalar() with this +query as the first argument, and other arguments followed, where +engine is the GinoEngine to which the metadata +(Gino) is bound, while metadata is found in this query.
+

+ +

+async status(*multiparams, **params)¶: Returns engine.status() with this +query as the first argument, and other arguments followed, where +engine is the GinoEngine to which the metadata +(Gino) is bound, while metadata is found in this query.
+

+ +

+timeout(timeout)¶

Shortcut to set execution option timeout in a chaining call.

Read execution_options() for more +information.

+ +

+ + +

+ + + +
+ This work is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License. +

+ +

gino.api module

+ + +

+ Add your language here. +

+ +

+ +

+ + + + + + + + + + + \ No newline at end of file diff --git a/docs/en/1.1b2/reference/api/gino.bakery.html b/docs/en/1.1b2/reference/api/gino.bakery.html new file mode 100644 index 0000000..aea15e3 --- /dev/null +++ b/docs/en/1.1b2/reference/api/gino.bakery.html @@ -0,0 +1,323 @@ + + + + + + + + gino.bakery module - GINO 1.1.0b2 documentation + + + + + + + + + + + +

+ + +

Tutorials

How-to Guides

Explanation

Reference

Reference
- API Reference
- Extensions
- History
+
API Reference
- gino package
+
Extensions
History

+ +

gino.bakery module¶

+class gino.bakery.BakedQuery(elem, metadata, hash_=None)¶

Bases: gino.api.GinoExecutor

Represents a pre-compiled and possibly prepared query for faster execution.

BakedQuery is created by Bakery.bake(), and can be executed by +GinoEngine or GinoConnection. If there +is a proper bind in the baked query, contextual execution APIs inherited from +GinoExecutor can also be used.

New in version 1.1.

+property bind¶: Internal API to provide a proper bind if found.
+

+ +

+property compiled_sql¶: Internal API to get the SQLAlchemy compiled sql context.
+

+ +

+execution_options(**kwargs)¶

Set execution options on a shadow query of this baked query.

The execution options set in this method won’t affect the execution options in +the baked query.

Read execution_options() for more +information.

Parameters: options – Multiple execution options.
+
Returns: A shadow of the baked query with new execution options but still +functions as a baked query.
+

+ +

+get(_)¶

Internal API to get the compiled_sql.

Parameters: _ – Ignored.
+

+ +

+property query¶: Internal API to get the query instance before compilation.
+

+ +

+property sql¶: Internal API to get the compiled raw SQL.
+

+ +

+class gino.bakery.Bakery¶

Bases: object

Factory and warehouse of baked queries.

You may provide a bakery to a GinoEngine during creation as +the bakery keyword argument, and the engine will bake the queries and create +corresponding prepared statements for each of the connections in the pool.

A Gino instance has a built-in bakery, +it’s automatically given to the engine during set_bind() or +with_bind().

New in version 1.1.

+bake(func_or_elem=None, **execution_options)¶

Bake a query.

You can bake raw SQL strings or SQLAlchemy Core query instances. This method +adds the given query into a queue in the bakery, and bakes it only when the +bakery is set to an GinoEngine from which the bakery could +learn about the SQL dialect and compile the queries into SQL. Once done, the +bakery is “closed”, you can neither give it to another engine, nor use it to +bake more queries.

Parameters

func_or_elem – A str or a SQLAlchemy Core query instance, or a +function that returns such results.
execution_options – Shortcut to add SQLAlchemy execution options to the +query.

Returns

A BakedQuery instance.

+ +

+query_cls¶: alias of BakedQuery
+

+ +

+ + +

+ + + +
+ This work is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License. +

+ +

gino.bakery module

+ + +

+ Add your language here. +

+ +

+ +

+ + + + + + + + + + + \ No newline at end of file diff --git a/docs/en/1.1b2/reference/api/gino.crud.html b/docs/en/1.1b2/reference/api/gino.crud.html new file mode 100644 index 0000000..4124ac3 --- /dev/null +++ b/docs/en/1.1b2/reference/api/gino.crud.html @@ -0,0 +1,653 @@ + + + + + + + + gino.crud module - GINO 1.1.0b2 documentation + + + + + + + + + + + +

+ + +

Tutorials

How-to Guides

Explanation

Reference

Reference
- API Reference
- Extensions
- History
+
API Reference
- gino package
+
Extensions
History

+ +

gino.crud module¶

+class gino.crud.Alias(model, *args, **kwargs)¶

Bases: object

Experimental proxy for table alias on model.

+distinct(*columns)¶

+ +

+load(*column_names, **relationships)¶

+ +

+on(on_clause)¶

+ +

+class gino.crud.CRUDModel(**values)¶

Bases: gino.declarative.Model

The base class for models with CRUD support.

Don’t inherit from this class directly, because it has no metadata. Use +db.Model instead.

+classmethod alias(*args, **kwargs)¶: Experimental proxy for table alias on model.
+

+ +

+append_where_primary_key(q)¶

Append where clause to locate this model instance by primary on the +given query, and return the new query.

This is mostly used internally in GINO, but also available for such +usage:

await user.append_where_primary_key(User.query).gino.first()
+

+

which is identical to:

await user.query.gino.first()
+

+

Deprecated since version 0.7.6: Use lookup() instead.

+ +

+create(bind=None, timeout=<object object>, **values)¶

This create behaves a bit different on model classes compared to model +instances.

On model classes, create will create a new model instance and insert +it into database. On model instances, create will just insert the +instance into the database.

Under the hood create() uses INSERT ... RETURNING ... to +create the new model instance and load it with database default data if +not specified.

Some examples:

user1 = await User.create(name='fantix', age=32)
+user2 = User(name='gino', age=42)
+await user2.create()
+

+

Parameters

bind – A GinoEngine to execute the +INSERT statement with, or None (default) to use the bound +engine on the metadata (Gino).
timeout – Seconds to wait for the database to finish executing, +None for wait forever. By default it will use the timeout +execution option value if unspecified.
values – Keyword arguments are pairs of attribute names and their +initial values. Only available when called on a model class.

Returns

The instance of this model class (newly created or existing).

+ +

+delete¶

Similar to update(), this delete is also different on model +classes than on model instances.

On model classes delete is an attribute of type +Delete for massive deletes, for +example:

await User.delete.where(User.enabled.is_(False)).gino.status()
+

+

Similarly you can add a returning() +clause to the query and it shall return the deleted rows as model objects.

And on model instances, delete() is a method to remove the +corresponding row in the database of this model instance. and returns the +status returned from the database:

print(await user.delete())  # e.g. prints DELETE 1
+

+

Note

delete() only removes the row from database, it does not affect the +current model instance.

Parameters

bind – An optional GinoEngine if current +metadata (Gino) has no bound engine, or specifying a +different GinoEngine to execute the DELETE.
timeout – Seconds to wait for the database to finish executing, +None for wait forever. By default it will use the timeout +execution option value if unspecified.

+ +

+classmethod distinct(*columns)¶: Experimental loader feature to yield only distinct instances by given +columns.
+

+ +

+async classmethod get(ident, bind=None, timeout=<object object>)¶

Get an instance of this model class by primary key.

For example:

user = await User.get(request.args.get('user_id'))
+

+

Parameters

ident – Value of the primary key. For composite primary keys this +should be a tuple of values for all keys in database order, or a dict +of names (or position numbers in database order starting from zero) +of all primary keys to their values.
bind – A GinoEngine to execute the +INSERT statement with, or None (default) to use the bound +engine on the metadata (Gino).
timeout – Seconds to wait for the database to finish executing, +None for wait forever. By default it will use the timeout +execution option value if unspecified.

Returns

An instance of this model class, or None if no such row.

+ +

+classmethod in_query(query)¶

Convenient method to get a Model object when using subqueries.

With this method, the columns are loaded into the original models when +being used in subqueries. For example:

query = query.alias('users')
+MyUser = User.in_query(query)
+
+loader = MyUser.distinct(User1.id).load()
+users = await query.gino.load(loader).all()
+

+

+ +

+classmethod load(*column_names, **relationships)¶

Populates a loader.Loader instance to be used by the +loader execution option in order to customize the loading behavior +to load specified fields into instances of this model.

The basic usage of this method is to provide the loader execution +option (if you are looking for reloading +the instance from database, check get() or query) for a +given query.

u = await User.query.gino.load(User.load('id', 'name')).first()
+

+

Tip

gino.load is a shortcut for setting the execution option +loader.

This will populate a User instance with only id and name +values, all the rest are simply None even if the query actually +returned all the column values.

q = User.join(Team).select()
+u = await q.gino.load(User.load(team=Team)).first()
+

+

This will load two instances of model User and Team, returning +the User instance with u.team set to the Team instance.

Both positional and keyword arguments can be used ath the same time. If +they are both omitted, like Team.load(), it is equivalent to just +Team as a loader.

Additionally, a loader.Loader instance can also be used to +generate queries, as its structure is usually the same as the query:

u = await User.load(team=Team).query.gino.first()
+

+

This generates a query like this:

SELECT users.xxx, ..., teams.xxx, ...
+  FROM users LEFT JOIN teams
+    ON ...
+

+

u = await User.load(
+    team=Team.on(User.team_id == Team.id)).gino.first()
+

+

And you can use both load() and on() at the same time +in a chain, in whatever order suits you.

See also

+ +

+lookup()¶

Generate where-clause expression to locate this model instance.

Returns: +

New in version 0.7.6.

+ +

+classmethod none_as_none(enabled=True)¶

+ +

+classmethod on(on_clause)¶: Customize the on-clause for the auto-generated outer join query.
+
+
Note
+
This has no effect when provided as the loader execution option +for a given query.
+
+
+
See also
+
load()
+
+

+ +

+query¶: Get a SQLAlchemy query clause of the table behind this model. This equals +to sqlalchemy.select([self.__table__]). If this attribute is retrieved on a +model instance, then a where clause to locate this instance by its primary +key is appended to the returning query clause. This model type is set as +the execution option model in the returning clause, so by default the +query yields instances of this model instead of database rows.
+

+ +

+select()¶

Build a query to retrieve only specified columns from this table.

This method accepts positional string arguments as names of attributes to +retrieve, and returns a Select for +query. The returning query object is always set with two execution options:

model is set to this model type
return_model is set to False

So that by default it always return rows instead of model instances, while +column types can be inferred correctly by the model option.

For example:

async for row in User.select('id', 'name').gino.iterate():
+    print(row['id'], row['name'])
+

+

db_age = await user.select('age').gino.scalar()
+

+

See also

+ +

+to_dict()¶

Convenient method to generate a dict from this model instance.

See also

json_support

+ +

+update¶

This update behaves quite different on model classes rather than model +instances.

On model classes, update is an attribute of type +Update for massive updates, for +example:

await User.update.values(enabled=True).where(...).gino.status()
+

+

Like query, the update query also has the model execution +option of this model, so if you use the +returning() clause, the query shall +return model objects.

await user.update(name='new name', age=32).apply()
+

+

Here, the await ... apply() executes the +actual UPDATE SQL in the database, while user.update() only makes +changes in the memory, and collect all changes into an +UpdateRequest instance.

+ +

+class gino.crud.QueryModel¶

Bases: type

Metaclass of Model classes used for subqueries.

+ +

+class gino.crud.UpdateRequest(instance: gino.crud.CRUDModel)¶

Bases: object

A collection of attributes and their new values to update on one model +instance.

+async apply(bind=None, timeout=<object object>)¶

Apply pending updates into database by executing an UPDATE SQL.

Parameters

bind – A GinoEngine to execute the SQL, or +None (default) to use the bound engine in the metadata.
timeout – Seconds to wait for the database to finish executing, +None for wait forever. By default it will use the timeout +execution option value if unspecified.

Returns

self for chaining calls.

+ +

+update(**values)¶

Set given attributes on the bound model instance, and add them into +the update collections for apply().

user.update(age=32, disabled=True)
+

+

Updated values can be SQLAlchemy expressions, for example an atomic +increment for user balance looks like this:

await user.update(balance=User.balance + 100).apply()
+

+

Note

+ +

+ + +

+ + + +
+ This work is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License. +

+ +

gino.crud module

+ + +

+ Add your language here. +

+ +

+ +

+ + + + + + + + + + + \ No newline at end of file diff --git a/docs/en/1.1b2/reference/api/gino.declarative.html b/docs/en/1.1b2/reference/api/gino.declarative.html new file mode 100644 index 0000000..3dd82df --- /dev/null +++ b/docs/en/1.1b2/reference/api/gino.declarative.html @@ -0,0 +1,401 @@ + + + + + + + + gino.declarative module - GINO 1.1.0b2 documentation + + + + + + + + + + + +

+ + +

Tutorials

How-to Guides

Explanation

Reference

Reference
- API Reference
- Extensions
- History
+
API Reference
- gino package
+
Extensions
History

+ +

gino.declarative module¶

+class gino.declarative.ColumnAttribute(prop_name, column)¶

Bases: object

The type of the column wrapper attributes on GINO models.

This is the core utility to enable GINO models so that:

Accessing a column attribute on a model class returns the column itself
Accessing a column attribute on a model instance returns the value for that column

This utility is customizable by defining __attr_factory__ in the model class.

+ +

+class gino.declarative.InvertDict(*args, **kwargs)¶

Bases: dict

A custom dict that allows getting keys by values.

Used internally by Model.

+invert_get(value, default=None)¶

Get key by value.

Parameters

value – A value in this dict.
default – If specified value doesn’t exist, return default.

Returns

The corresponding key if the value is found, or default otherwise.

+ +

+class gino.declarative.Model¶

Bases: object

The base class of GINO models.

from sqlalchemy import MetaData, Column, Integer, String
+from gino.declarative import declarative_base
+
+Model = declarative_base()
+
+class User(db.Model):
+    __tablename__ = "users"
+    id = Column(Integer(), primary_key=True)
+    name = Column(String())
+

+

The name of the columns are automatically set using the attribute name.

u = User()
+assert u.name is None
+
+u.name = "daisy"
+assert u.name == "daisy"
+

+

Note

Accessing column attributes on a model instance will NOT trigger any database +operation.

Constraint and Index are +also allowed as model class attributes. Their attribute names are not used.

A concrete model class can be used as a replacement of the +Table it reflects in SQLAlchemy queries. The model class +is also iterable, yielding all the Column instances +defined in the model.

Other built-in class attributes:

__metadata__
+
This is supposed to be set by declarative_base() and used only during +subclass construction. Still, this can be treated as a read-only attribute to +find out which MetaData this model is bound to.
+
__tablename__
+
This is a required attribute to define a concrete model, meaning a +sqlalchemy.schema.Table instance will be created, added to the bound +MetaData and set to the class attribute __table__. +Not defining __tablename__ will result in an abstract model - no table +instance will be created, and instances of an abstract model are meaningless.
+
__table__
+
This should usually be treated as an auto-generated read-only attribute storing +the sqlalchemy.schema.Table instance.
+
__attr_factory__
+
An attribute factory that is used to wrap the actual +Column instance on the model class, so that the access +to the column attributes on model instances is redirected to the in-memory value +store. The default factory is ColumnAttribute, can be override.
+
__values__
+
The internal in-memory value store as a dict, only available on model +instances. Accessing column attributes is equivalent to accessing __values__.
+

+ +

+gino.declarative.declarative_base(metadata, model_classes=(<class 'gino.declarative.Model'>, ), name='Model')¶

Create a base GINO model class for declarative table definition.

Parameters

metadata – A MetaData instance to contain the +tables.
model_classes – Base class(es) of the base model class to be created. Default: +Model.
name – The class name of the base model class to be created. Default: +Model.

Returns

A new base model class.

+ +

+gino.declarative.declared_attr(m=None, *, with_table=False)¶

Mark a class-level method as a factory of attribute.

class TrackedMixin:
+    created = db.Column(db.DateTime(timezone=True))
+
+    @db.declared_attr
+    def unique_id(cls):
+        return db.Column(db.Integer())
+
+    @db.declared_attr
+    def unique_constraint(cls):
+        return db.UniqueConstraint('unique_id')
+
+    @db.declared_attr
+    def poly(cls):
+        if cls.__name__ == 'Thing':
+            return db.Column(db.Unicode())
+
+    @db.declared_attr
+    def __table_args__(cls):
+        if cls.__name__ == 'Thing':
+            return db.UniqueConstraint('poly'),
+

+

Note

This doesn’t work if the model already had a __table__.

Changed in version 1.1: Added with_table parameter which works after the __table__ is created:

class User(db.Model):
+    __tablename__ = "users"
+
+    ...
+
+    @db.declared_attr(with_table=True)
+    def table_name(cls):
+        # this is called only once when defining the class
+        return cls.__table__.name
+
+assert User.table_name == "users"
+

+

+ +

+ + +

+ + + +
+ This work is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License. +

+ +

gino.declarative module

+ + +

+ Add your language here. +

+ +

+ +

+ + + + + + + + + + + \ No newline at end of file diff --git a/docs/en/1.1b2/reference/api/gino.dialects.aiomysql.html b/docs/en/1.1b2/reference/api/gino.dialects.aiomysql.html new file mode 100644 index 0000000..7283f39 --- /dev/null +++ b/docs/en/1.1b2/reference/api/gino.dialects.aiomysql.html @@ -0,0 +1,588 @@ + + + + + + + + gino.dialects.aiomysql module - GINO 1.1.0b2 documentation + + + + + + + + + + + +

+ + +

Tutorials

How-to Guides

Explanation

Reference

Reference
- API Reference
- Extensions
- History
+
API Reference
- gino package
+
Extensions
History

+ +

gino.dialects.aiomysql module¶

+class gino.dialects.aiomysql.AiomysqlDBAPI¶

Bases: gino.dialects.base.BaseDBAPI

+paramstyle = 'format'¶

+ +

+class gino.dialects.aiomysql.AiomysqlDialect(*args, bakery=None, **kwargs)¶

Bases: sqlalchemy.dialects.mysql.base.MySQLDialect, gino.dialects.base.AsyncDialectMixin

+colspecs = {<class 'sqlalchemy.dialects.mysql.types._IntegerType'>: <class 'sqlalchemy.dialects.mysql.types._IntegerType'>, <class 'sqlalchemy.dialects.mysql.types._NumericType'>: <class 'sqlalchemy.dialects.mysql.types._NumericType'>, <class 'sqlalchemy.dialects.mysql.types._FloatType'>: <class 'sqlalchemy.dialects.mysql.types._FloatType'>, <class 'sqlalchemy.sql.sqltypes.Numeric'>: <class 'sqlalchemy.dialects.mysql.types.NUMERIC'>, <class 'sqlalchemy.sql.sqltypes.Float'>: <class 'sqlalchemy.dialects.mysql.types.FLOAT'>, <class 'sqlalchemy.sql.sqltypes.Time'>: <class 'sqlalchemy.dialects.mysql.types.TIME'>, <class 'sqlalchemy.sql.sqltypes.Enum'>: <class 'gino.dialects.aiomysql.AsyncEnum'>, <class 'sqlalchemy.sql.sqltypes.MatchType'>: <class 'sqlalchemy.dialects.mysql.types._MatchType'>, <class 'sqlalchemy.sql.sqltypes.JSON'>: <class 'sqlalchemy.dialects.mysql.json.JSON'>, <class 'sqlalchemy.sql.sqltypes.JSON.JSONIndexType'>: <class 'sqlalchemy.dialects.mysql.json.JSONIndexType'>, <class 'sqlalchemy.sql.sqltypes.JSON.JSONPathType'>: <class 'sqlalchemy.dialects.mysql.json.JSONPathType'>, <class 'sqlalchemy.dialects.mysql.enumerated.ENUM'>: <class 'gino.dialects.aiomysql.AsyncEnum'>, <class 'sqlalchemy.sql.sqltypes.NullType'>: <class 'gino.dialects.aiomysql.GinoNullType'>}¶

+ +

+cursor_cls¶: alias of DBAPICursor
+

+ +

+dbapi_class¶: alias of AiomysqlDBAPI
+

+ +

+driver = 'aiomysql'¶

+ +

+execution_ctx_cls¶: alias of AiomysqlExecutionContext
+

+ +

+async get_isolation_level(connection)¶

Given a DBAPI connection, return its isolation level.

When working with a _engine.Connection object, +the corresponding +DBAPI connection may be procured using the +_engine.Connection.connection accessor.

Note that this is a dialect-level method which is used as part +of the implementation of the _engine.Connection and +_engine.Engine isolation level facilities; +these APIs should be preferred for most typical use cases.

See also

_engine.Connection.get_isolation_level() +- view current level

_engine.Connection.default_isolation_level +- view default level

:paramref:`.Connection.execution_options.isolation_level` - +set per _engine.Connection isolation level

:paramref:`_sa.create_engine.isolation_level` - +set per _engine.Engine isolation level

+ +

+async has_table(connection, table_name, schema=None)¶

Check the existence of a particular table in the database.

Given a _engine.Connection object and a string +table_name, return True if the given table (possibly within +the specified schema) exists in the database, False +otherwise.

+ +

+init_kwargs = {'auth_plugin', 'autocommit', 'bakery', 'charset', 'client_flag', 'connect_timeout', 'conv', 'cursorclass', 'db', 'host', 'init_command', 'local_infile', 'loop', 'maxsize', 'minsize', 'no_delay', 'password', 'pool_recycle', 'port', 'prebake', 'program_name', 'read_default_file', 'read_default_group', 'server_public_key', 'sql_mode', 'ssl', 'unix_socket', 'use_unicode', 'user'}¶

+ +

+async init_pool(url, loop, pool_class=None)¶

+ +

+on_connect()¶

Return a callable which sets up a newly created DBAPI connection.

The callable should accept a single argument “conn” which is the +DBAPI connection itself. The inner callable has no +return value.

E.g.:

class MyDialect(default.DefaultDialect):
+    # ...
+
+    def on_connect(self):
+        def do_on_connect(connection):
+            connection.execute("SET SPECIAL FLAGS etc")
+
+        return do_on_connect
+

+

This is used to set dialect-wide per-connection options such as +isolation modes, Unicode modes, etc.

If None is returned, no event listener is generated.

Returns: a callable that accepts a single DBAPI connection as an +argument, or None.
+

See also

Dialect.connect() - allows the DBAPI connect() sequence +itself to be controlled.

+ +

+postfetch_lastrowid = False¶

+ +

+async set_isolation_level(connection, level)¶

Given a DBAPI connection, set its isolation level.

Note that this is a dialect-level method which is used as part +of the implementation of the _engine.Connection and +_engine.Engine +isolation level facilities; these APIs should be preferred for +most typical use cases.

See also

_engine.Connection.get_isolation_level() +- view current level

_engine.Connection.default_isolation_level +- view default level

:paramref:`.Connection.execution_options.isolation_level` - +set per _engine.Connection isolation level

:paramref:`_sa.create_engine.isolation_level` - +set per _engine.Engine isolation level

+ +

+statement_compiler¶: alias of sqlalchemy.dialects.mysql.base.MySQLCompiler
+

+ +

+support_prepare = False¶

+ +

+support_returning = False¶

+ +

+supports_native_decimal = True¶

+ +

+transaction(raw_conn, args, kwargs)¶

+ +

+class gino.dialects.aiomysql.AiomysqlExecutionContext¶

Bases: gino.dialects.base.ExecutionContextOverride, sqlalchemy.dialects.mysql.base.MySQLExecutionContext

+get_affected_rows()¶

+ +

+get_lastrowid()¶

return self.cursor.lastrowid, or equivalent, after an INSERT.

This may involve calling special cursor functions, +issuing a new SELECT on the cursor (or a new one), +or returning a stored value that was +calculated within post_exec().

This function will only be called for dialects +which support “implicit” primary key generation, +keep preexecute_autoincrement_sequences set to False, +and when no explicit id value was bound to the +statement.

The function is called once, directly after +post_exec() and before the transaction is committed +or ResultProxy is generated. If the post_exec() +method assigns a value to self._lastrowid, the +value is used in place of calling get_lastrowid().

Note that this method is not equivalent to the +lastrowid method on ResultProxy, which is a +direct proxy to the DBAPI lastrowid accessor +in all cases.

+ +

+class gino.dialects.aiomysql.AiomysqlIterator(context, cursor)¶

Bases: gino.dialects.base.Cursor

+async forward(n, *, timeout=<object object>)¶

+ +

+async many(n, *, timeout=<object object>)¶

+ +

+async next(*, timeout=<object object>)¶

+ +

+class gino.dialects.aiomysql.AsyncEnum(*enums, **kw)¶

Bases: sqlalchemy.dialects.mysql.enumerated.ENUM

+async create_async(bind=None, checkfirst=True)¶

+ +

+async drop_async(bind=None, checkfirst=True)¶

+ +

+class gino.dialects.aiomysql.DBAPICursor(dbapi_conn)¶

Bases: gino.dialects.base.DBAPICursor

+async async_execute(query, timeout, args, limit=0, many=False)¶

+ +

+property description¶

+ +

+async execute_baked(baked_query, timeout, args, one)¶

+ +

+get_statusmsg()¶

+ +

+iterate(context)¶

+ +

+async prepare(context, clause=None)¶

+ +

+class gino.dialects.aiomysql.GinoNullType¶

Bases: sqlalchemy.sql.sqltypes.NullType

+result_processor(dialect, coltype)¶

Return a conversion function for processing result row values.

Returns a callable which will receive a result row column +value as the sole positional argument and will return a value +to return to the user.

If processing is not necessary, the method should return None.

Parameters

dialect – Dialect instance in use.
coltype – DBAPI coltype argument received in cursor.description.

+ +

+class gino.dialects.aiomysql.Pool(url, loop, init=None, bakery=None, prebake=True, **kwargs)¶

+async acquire(*, timeout=None)¶

+ +

+async close()¶

+ +

+property raw_pool¶

+ +

+async release(conn)¶

+ +

+repr(color)¶

+ +

+class gino.dialects.aiomysql.Transaction(conn, set_isolation=None)¶

Bases: gino.dialects.base.Transaction

+async begin()¶

+ +

+async commit()¶

+ +

+property raw_transaction¶

+ +

+async rollback()¶

+ +

+ + +

+ + + +
+ This work is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License. +

+ +

gino.dialects.aiomysql module

+ + +

+ Add your language here. +

+ +

+ +

+ + + + + + + + + + + \ No newline at end of file diff --git a/docs/en/1.1b2/reference/api/gino.dialects.asyncpg.html b/docs/en/1.1b2/reference/api/gino.dialects.asyncpg.html new file mode 100644 index 0000000..f9f4ab4 --- /dev/null +++ b/docs/en/1.1b2/reference/api/gino.dialects.asyncpg.html @@ -0,0 +1,598 @@ + + + + + + + + gino.dialects.asyncpg module - GINO 1.1.0b2 documentation + + + + + + + + + + + +

+ + +

Tutorials

How-to Guides

Explanation

Reference

Reference
- API Reference
- Extensions
- History
+
API Reference
- gino package
+
Extensions
History

+ +

gino.dialects.asyncpg module¶

+class gino.dialects.asyncpg.AsyncEnum(*enums, **kw)¶

Bases: sqlalchemy.dialects.postgresql.base.ENUM

+async create_async(bind=None, checkfirst=True)¶

+ +

+async drop_async(bind=None, checkfirst=True)¶

+ +

+class gino.dialects.asyncpg.AsyncpgCompiler(dialect, statement, column_keys=None, inline=False, **kwargs)¶

Bases: sqlalchemy.dialects.postgresql.base.PGCompiler

+property bindtemplate¶

+ +

+class gino.dialects.asyncpg.AsyncpgCursor(context, cursor)¶

Bases: gino.dialects.base.Cursor

+async forward(n, *, timeout=<object object>)¶

+ +

+async many(n, *, timeout=<object object>)¶

+ +

+async next(*, timeout=<object object>)¶

+ +

+class gino.dialects.asyncpg.AsyncpgDBAPI¶

Bases: gino.dialects.base.BaseDBAPI

+Error = (<class 'asyncpg.exceptions._base.PostgresError'>, <class 'asyncpg.exceptions._base.InterfaceError'>)¶

+ +

+class gino.dialects.asyncpg.AsyncpgDialect(*args, bakery=None, **kwargs)¶

Bases: sqlalchemy.dialects.postgresql.base.PGDialect, gino.dialects.base.AsyncDialectMixin

+colspecs = {<class 'sqlalchemy.sql.sqltypes.ARRAY'>: <class 'sqlalchemy.dialects.postgresql.array.ARRAY'>, <class 'sqlalchemy.sql.sqltypes.Interval'>: <class 'sqlalchemy.dialects.postgresql.base.INTERVAL'>, <class 'sqlalchemy.sql.sqltypes.Enum'>: <class 'gino.dialects.asyncpg.AsyncEnum'>, <class 'sqlalchemy.sql.sqltypes.JSON.JSONPathType'>: <class 'gino.dialects.asyncpg.AsyncpgJSONPathType'>, <class 'sqlalchemy.sql.sqltypes.JSON'>: <class 'sqlalchemy.dialects.postgresql.json.JSON'>, <class 'sqlalchemy.dialects.postgresql.base.ENUM'>: <class 'gino.dialects.asyncpg.AsyncEnum'>, <class 'sqlalchemy.sql.sqltypes.NullType'>: <class 'gino.dialects.asyncpg.GinoNullType'>}¶

+ +

+cursor_cls¶: alias of DBAPICursor
+

+ +

+dbapi_class¶: alias of AsyncpgDBAPI
+

+ +

+driver = 'asyncpg'¶

+ +

+execution_ctx_cls¶: alias of AsyncpgExecutionContext
+

+ +

+async get_isolation_level(connection)¶: Given an asyncpg connection, return its isolation level.
+

+ +

+async has_schema(connection, schema)¶

+ +

+async has_sequence(connection, sequence_name, schema=None)¶

Check the existence of a particular sequence in the database.

Given a _engine.Connection object and a string +sequence_name, return True if the given sequence exists in +the database, False otherwise.

+ +

+async has_table(connection, table_name, schema=None)¶

Check the existence of a particular table in the database.

Given a _engine.Connection object and a string +table_name, return True if the given table (possibly within +the specified schema) exists in the database, False +otherwise.

+ +

+async has_type(connection, type_name, schema=None)¶

+ +

+init_kwargs = {'bakery', 'command_timeout', 'connection_class', 'database', 'host', 'init', 'loop', 'max_cacheable_statement_size', 'max_cached_statement_lifetime', 'max_inactive_connection_lifetime', 'max_queries', 'max_size', 'min_size', 'passfile', 'password', 'port', 'prebake', 'server_settings', 'setup', 'ssl', 'statement_cache_size', 'timeout', 'user'}¶

+ +

+async init_pool(url, loop, pool_class=None)¶

+ +

+on_connect()¶

Return a callable which sets up a newly created DBAPI connection.

The callable should accept a single argument “conn” which is the +DBAPI connection itself. The inner callable has no +return value.

E.g.:

class MyDialect(default.DefaultDialect):
+    # ...
+
+    def on_connect(self):
+        def do_on_connect(connection):
+            connection.execute("SET SPECIAL FLAGS etc")
+
+        return do_on_connect
+

+

This is used to set dialect-wide per-connection options such as +isolation modes, Unicode modes, etc.

If None is returned, no event listener is generated.

Returns: a callable that accepts a single DBAPI connection as an +argument, or None.
+

See also

Dialect.connect() - allows the DBAPI connect() sequence +itself to be controlled.

+ +

+async set_isolation_level(connection, level)¶: Given an asyncpg connection, set its isolation level.
+

+ +

+statement_compiler¶: alias of AsyncpgCompiler
+

+ +

+supports_native_decimal = True¶

+ +

+transaction(raw_conn, args, kwargs)¶

+ +

+class gino.dialects.asyncpg.AsyncpgExecutionContext¶: Bases: gino.dialects.base.ExecutionContextOverride, sqlalchemy.dialects.postgresql.base.PGExecutionContext
+

+ +

+class gino.dialects.asyncpg.AsyncpgIterator(context, iterator)¶: Bases: object
+

+ +

+class gino.dialects.asyncpg.AsyncpgJSONPathType¶

Bases: sqlalchemy.dialects.postgresql.json.JSONPathType

+bind_processor(dialect)¶

Return a conversion function for processing bind values.

Returns a callable which will receive a bind parameter value +as the sole positional argument and will return a value to +send to the DB-API.

If processing is not necessary, the method should return None.

Parameters: dialect – Dialect instance in use.
+

+ +

+class gino.dialects.asyncpg.DBAPICursor(dbapi_conn)¶

Bases: gino.dialects.base.DBAPICursor

+async async_execute(query, timeout, args, limit=0, many=False)¶

+ +

+property description¶

+ +

+async execute_baked(baked_query, timeout, args, one)¶

+ +

+get_statusmsg()¶

+ +

+async prepare(context, clause=None)¶

+ +

+class gino.dialects.asyncpg.GinoNullType¶

Bases: sqlalchemy.sql.sqltypes.NullType

+result_processor(dialect, coltype)¶

Return a conversion function for processing result row values.

Returns a callable which will receive a result row column +value as the sole positional argument and will return a value +to return to the user.

If processing is not necessary, the method should return None.

Parameters

dialect – Dialect instance in use.
coltype – DBAPI coltype argument received in cursor.description.

+ +

+class gino.dialects.asyncpg.NullPool(url, loop, **kwargs)¶

+async acquire(*, timeout=None)¶

+ +

+async close()¶

+ +

+property raw_pool¶

+ +

+async release(conn)¶

+ +

+repr(color)¶

+ +

+class gino.dialects.asyncpg.Pool(url, loop, bakery=None, prebake=True, **kwargs)¶

+async acquire(*, timeout=None)¶

+ +

+async close()¶

+ +

+property raw_pool¶

+ +

+async release(conn)¶

+ +

+repr(color)¶

+ +

+class gino.dialects.asyncpg.PreparedStatement(prepared, clause=None)¶: Bases: gino.dialects.base.PreparedStatement
+

+ +

+class gino.dialects.asyncpg.Transaction(tx)¶

Bases: gino.dialects.base.Transaction

+async begin()¶

+ +

+async commit()¶

+ +

+property raw_transaction¶

+ +

+async rollback()¶

+ +

+ + +

+ + + +
+ This work is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License. +

+ +

gino.dialects.asyncpg module

+ + +

+ Add your language here. +

+ +

+ +

+ + + + + + + + + + + \ No newline at end of file diff --git a/docs/en/1.1b2/reference/api/gino.dialects.base.html b/docs/en/1.1b2/reference/api/gino.dialects.base.html new file mode 100644 index 0000000..133cee8 --- /dev/null +++ b/docs/en/1.1b2/reference/api/gino.dialects.base.html @@ -0,0 +1,482 @@ + + + + + + + + gino.dialects.base module - GINO 1.1.0b2 documentation + + + + + + + + + + + +

+ + +

Tutorials

How-to Guides

Explanation

Reference

Reference
- API Reference
- Extensions
- History
+
API Reference
- gino package
+
Extensions
History

+ +

gino.dialects.base module¶

+class gino.dialects.base.AsyncDialectMixin¶

Bases: object

+compile(elem, *multiparams, **params)¶

+ +

+cursor_cls¶: alias of DBAPICursor
+

+ +

+classmethod dbapi()¶

+ +

+dbapi_class¶: alias of BaseDBAPI
+

+ +

+async init_pool(url, loop, pool_class=None)¶

+ +

+support_prepare = True¶

+ +

+support_returning = True¶

+ +

+transaction(raw_conn, args, kwargs)¶

+ +

+class gino.dialects.base.BaseDBAPI¶

Bases: object

+static Binary(x)¶

+ +

+Error¶: alias of builtins.Exception
+

+ +

+paramstyle = 'numeric'¶

+ +

+class gino.dialects.base.Cursor¶

Bases: object

+async forward(n, *, timeout=<object object>)¶

+ +

+async many(n, *, timeout=<object object>)¶

+ +

+async next(*, timeout=<object object>)¶

+ +

+class gino.dialects.base.DBAPICursor¶

Bases: object

+async async_execute(query, timeout, args, limit=0, many=False)¶

+ +

+property description¶

+ +

+execute(statement, parameters)¶

+ +

+async execute_baked(baked_query, timeout, args, one)¶

+ +

+executemany(statement, parameters)¶

+ +

+get_statusmsg()¶

+ +

+async prepare(context, clause=None)¶

+ +

+class gino.dialects.base.ExecutionContextOverride¶

Bases: object

+baked_query = None¶

+ +

+get_affected_rows()¶

+ +

+get_lastrowid()¶

+ +

+get_result_proxy()¶

+ +

+loader¶

+ +

+model¶

+ +

+process_rows(rows, return_model=True)¶

+ +

+return_model¶

+ +

+timeout¶

+ +

+class gino.dialects.base.Pool¶

Bases: object

+async acquire(*, timeout=None)¶

+ +

+async close()¶

+ +

+property raw_pool¶

+ +

+async release(conn)¶

+ +

+repr(color)¶

+ +

+class gino.dialects.base.PreparedStatement(clause=None)¶

Bases: object

+async all(*multiparams, **params)¶

+ +

+async first(*multiparams, **params)¶

+ +

+iterate(*params, **kwargs)¶

+ +

+async scalar(*multiparams, **params)¶

+ +

+async status(*multiparams, **params)¶

+ +

+class gino.dialects.base.Transaction¶

Bases: object

+async begin()¶

+ +

+async commit()¶

+ +

+property raw_transaction¶

+ +

+async rollback()¶

+ +

+ + +

+ + + +
+ This work is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License. +

+ +

gino.dialects.base module

+ + +

+ Add your language here. +

+ +

+ +

+ + + + + + + + + + + \ No newline at end of file diff --git a/docs/en/1.1b2/reference/api/gino.dialects.html b/docs/en/1.1b2/reference/api/gino.dialects.html new file mode 100644 index 0000000..3efa8d1 --- /dev/null +++ b/docs/en/1.1b2/reference/api/gino.dialects.html @@ -0,0 +1,227 @@ + + + + + + + + gino.dialects package - GINO 1.1.0b2 documentation + + + + + + + + + + + +

+ + +

Tutorials

How-to Guides

Explanation

Reference

Reference
- API Reference
- Extensions
- History
+
API Reference
- gino package
+
Extensions
History

+ +

gino.dialects package¶

Submodules¶

Module contents¶

+ + +

+ + + +
+ This work is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License. +

+ +

gino.dialects package
- Submodules
- Module contents
+

+ + +

+ +

+ + +

+ Add your language here. +

+ +

+ +

+ + + + + + + + + + + \ No newline at end of file diff --git a/docs/en/1.1b2/reference/api/gino.engine.html b/docs/en/1.1b2/reference/api/gino.engine.html new file mode 100644 index 0000000..97e9986 --- /dev/null +++ b/docs/en/1.1b2/reference/api/gino.engine.html @@ -0,0 +1,718 @@ + + + + + + + + gino.engine module - GINO 1.1.0b2 documentation + + + + + + + + + + + +

+ + +

Tutorials

How-to Guides

Explanation

Reference

Reference
- API Reference
- Extensions
- History
+
API Reference
- gino package
+
Extensions
History

+ +

gino.engine module¶

+class gino.engine.GinoConnection(dialect, sa_conn, stack=None)¶

Bases: object

Represents an actual database connection.

This is the root of all query API like all(), first(), +one(), one_or_none(), scalar() or status(), +those on engine or query are simply wrappers of methods in this class.

Usually instances of this class are created by GinoEngine.acquire().

Note

See also

+async all(clause, *multiparams, **params)¶

Runs the given query in database, returns all results as a list.

This method accepts the same parameters taken by SQLAlchemy +execute(). You can pass in a raw +SQL string, or any SQLAlchemy query clauses.

+ +

+property dialect¶: The Dialect in use, inherited +from the engine created this connection.
+

+ +

+execution_options(**opt)¶

Set non-SQL options for the connection which take effect during +execution.

row = await conn.execution_options(model=None).first(User.query)
+

+

Parameters

return_model – Boolean to control whether the returning results +should be loaded into model instances, where the model class is +defined in another execution option model. Default is True.
model – Specifies the type of model instance to create on return. +This has no effect if return_model is set to False. Usually +in queries built by CRUD models, this execution option is +automatically set. For now, GINO only supports loading each row into +one type of model object, relationships are not supported. Please use +multiple queries for that. None for no postprocessing (default).
timeout – Seconds to wait for the query to finish. None for +no time out (default).
loader –
A loader expression to load the database rows into +specified objective structure. It can be either:
+
- A model class, so that the query will yield model instances of this +class. It is your responsibility to make sure all the columns of +this model is selected in the query.
- A Column instance, so that each result +will be only a single value of this column. Please note, if you +want to achieve fetching the very first value, you should use +first() instead of +scalar(). However, using directly +scalar() is a more direct way.
- A tuple nesting more loader expressions recursively.
- A callable() function that will be called for each row to +fully customize the result. Two positional arguments will be passed +to the function: the first is the row instance, the second is a context +object which is only present if nested else None.
- A Loader instance directly.
- Anything else will be treated as literal values thus returned as +whatever they are.
+

+ +

+async first(clause, *multiparams, **params)¶

Runs the given query in database, returns the first result.

If the query returns no result, this method will return None.

See all() for common query comments.

+ +

+async get_raw_connection(*, timeout=None)¶

Get the underlying database connection, acquire one if none present.

Parameters: timeout – Seconds to wait for the underlying acquiring
+
Returns: Underlying database connection instance depending on the +dialect in use
+
Raises: TimeoutError if the acquiring timed out
+

+ +

+iterate(clause, *multiparams, **params)¶

Creates a server-side cursor in database for large query results.

Cursors must work within transactions:

async with conn.transaction():
+    async for user in conn.iterate(User.query):
+        # handle each user without loading all users into memory
+

+

Alternatively, you can manually control how the cursor works:

async with conn.transaction():
+    cursor = await conn.iterate(User.query)
+    user = await cursor.next()
+    users = await cursor.many(10)
+

+

See also

+ +

+async scalar(clause, *multiparams, **params)¶

Runs the given query in database, returns the first result.

If the query returns no result, this method will return None.

See all() for common query comments.

+ +

+schema_for_object = <sqlalchemy.sql.schema._SchemaTranslateMap object>¶: A SQLAlchemy compatibility attribute, don’t use it for now, it bites.
+

+ +

+async status(clause, *multiparams, **params)¶

Runs the given query in database, returns the query status.

The returning query status depends on underlying database and the +dialect in use. For asyncpg it is a string, you can parse it like this: +https://git.io/v7oze

+ +

+transaction(*args, **kwargs)¶

Starts a database transaction.

There are two ways using this method: managed as an asynchronous +context manager:

async with conn.transaction() as tx:
+    # run query in transaction
+

+

or manually awaited:

tx = await conn.transaction()
+try:
+    # run query in transaction
+    await tx.commit()
+except Exception:
+    await tx.rollback()
+    raise
+

+

Where the tx is an instance of the +GinoTransaction class, feel free to read +more about it.

If this is a lazy connection, entering a transaction will cause a new +database connection acquired if none was present.

Transactions may support nesting depending on the dialect in use. For +example in asyncpg, starting a second transaction on the same +connection will create a save point in the database.

For now, the parameters are directly passed to underlying database +driver, read asyncpg.connection.Connection.transaction() for +asyncpg.

+ +

+class gino.engine.GinoEngine(dialect, pool, loop, logging_name=None, echo=None, execution_options=None)¶

Bases: object

Connects a Pool and +Dialect together to provide a source +of database connectivity and behavior.

A GinoEngine object is instantiated publicly using the +gino.create_engine() function or +db.set_bind() method.

See also

+acquire(*, timeout=None, reuse=False, lazy=False, reusable=True)¶

Acquire a connection from the pool.

There are two ways using this method - as an asynchronous context +manager:

async with engine.acquire() as conn:
+    # play with the connection
+

+

which will guarantee the connection is returned to the pool when +leaving the async with block; or as a coroutine:

conn = await engine.acquire()
+try:
+    # play with the connection
+finally:
+    await conn.release()
+

+

where the connection should be manually returned to the pool with +conn.release().

Within the same context (usually the same Task, see +also Transaction), a nesting acquire by default re

Parameters

timeout – Block up to timeout seconds until there is one free +connection in the pool. Default is None - block forever until +succeeded. This has no effect when lazy=True, and depends on the +actual situation when reuse=True.
reuse – Reuse the latest reusable acquired connection (before +it’s returned to the pool) in current context if there is one, or +borrow a new one if none present. Default is False for always +borrow a new one. This is useful when you are in a nested method call +series, wishing to use the same connection without passing it around +as parameters. See also: Transaction. A reusing +connection is not reusable even if reusable=True. If the reused +connection happened to be a lazy one, then the reusing connection is +lazy too.
lazy – Don’t acquire the actual underlying connection yet - do it +only when needed. Default is False for always do it immediately. +This is useful before entering a code block which may or may not make +use of a given connection object. Feeding in a lazy connection will +save the borrow-return job if the connection is never used. If +setting reuse=True at the same time, then the reused connection - +if any - applies the same laziness. For example, reusing a lazy +connection with lazy=False will cause the reused connection to +acquire an underlying connection immediately.
reusable – Mark this connection as reusable or otherwise. This +has no effect if it is a reusing connection. All reusable connections +are placed in a stack, any reusing acquire operation will always +reuse the top (latest) reusable connection. One reusable connection +may be reused by several reusing connections - they all share one +same underlying connection. Acquiring a connection with +reusable=False and reusing=False makes it a cleanly isolated +connection which is only referenced once here.

Returns

A GinoConnection object.

+ +

+async all(clause, *multiparams, **params)¶

Acquires a connection with reuse=True and runs +all() on it. reuse=True means you can safely +do this without borrowing more than one underlying connection:

async with engine.acquire():
+    await engine.all('SELECT ...')
+

+

The same applies for other query methods.

+ +

+async close()¶: Close the engine, by closing the underlying pool.
+

+ +

+compile(clause, *multiparams, **params)¶: A shortcut for compile() on +the dialect, returns raw SQL string and parameters according to the +rules of the dialect.
+

+ +

+connection_cls¶

Customizes the connection class to use, default is +GinoConnection.

alias of GinoConnection

+ +

+property current_connection¶

Gets the most recently acquired reusable connection in the context. +None if there is no such connection.

Returns: GinoConnection
+

+ +

+property dialect¶: Read-only property for the +Dialect of this engine.
+

+ +

+async first(clause, *multiparams, **params)¶: Runs first(), See all().
+

+ +

+iterate(clause, *multiparams, **params)¶

Creates a server-side cursor in database for large query results.

This requires that there is a reusable connection in the current +context, and an active transaction is present. Then its +GinoConnection.iterate() is executed and returned.

+ +

+async one(clause, *multiparams, **params)¶: Runs one(), See all().
+

+ +

+async one_or_none(clause, *multiparams, **params)¶: Runs one_or_none(), See all().
+

+ +

+property raw_pool¶: Read-only access to the underlying database connection pool instance. +This depends on the actual dialect in use, Pool +of asyncpg for example.
+

+ +

+repr(color=False)¶

+ +

+async scalar(clause, *multiparams, **params)¶: Runs scalar(), See all().
+

+ +

+async status(clause, *multiparams, **params)¶: Runs status(). See also all().
+

+ +

+transaction(*args, timeout=None, reuse=True, reusable=True, **kwargs)¶

Borrows a new connection and starts a transaction with it.

Different to GinoConnection.transaction(), transaction on engine +level supports only managed usage:

async with engine.transaction() as tx:
+    # play with transaction here
+

+

Where the implicitly acquired connection is available as +tx.connection.

The other arguments are the same as +transaction() on connection.

See also

GinoConnection.transaction()

GinoTransaction

Returns: A asynchronous context manager that yields a +GinoTransaction
+

+ +

+update_execution_options(**opt)¶: Update the default execution_options dictionary +of this GinoEngine.
+
+
See also
+
sqlalchemy.engine.Engine.update_execution_options()
+
GinoConnection.execution_options()
+
+

+ +

+ + +

+ + + +
+ This work is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License. +

+ +

gino.engine module

+ + +

+ Add your language here. +

+ +

+ +

+ + + + + + + + + + + \ No newline at end of file diff --git a/docs/en/1.1b2/reference/api/gino.exceptions.html b/docs/en/1.1b2/reference/api/gino.exceptions.html new file mode 100644 index 0000000..a2ae8e3 --- /dev/null +++ b/docs/en/1.1b2/reference/api/gino.exceptions.html @@ -0,0 +1,250 @@ + + + + + + + + gino.exceptions module - GINO 1.1.0b2 documentation + + + + + + + + + + + +

+ + +

Tutorials

How-to Guides

Explanation

Reference

Reference
- API Reference
- Extensions
- History
+
API Reference
- gino package
+
Extensions
History

+ +

gino.exceptions module¶

+exception gino.exceptions.GinoException¶: Bases: Exception
+

+ +

+exception gino.exceptions.InitializedError¶: Bases: gino.exceptions.GinoException
+

+ +

+exception gino.exceptions.MultipleResultsFound¶: Bases: gino.exceptions.GinoException
+

+ +

+exception gino.exceptions.NoResultFound¶: Bases: gino.exceptions.GinoException
+

+ +

+exception gino.exceptions.NoSuchRowError¶: Bases: gino.exceptions.GinoException
+

+ +

+exception gino.exceptions.UninitializedError¶: Bases: gino.exceptions.GinoException
+

+ +

+exception gino.exceptions.UnknownJSONPropertyError¶: Bases: gino.exceptions.GinoException
+

+ +

+ + +

+ + + +
+ This work is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License. +

+ +

gino.exceptions module

+ + +

+ Add your language here. +

+ +

+ +

+ + + + + + + + + + + \ No newline at end of file diff --git a/docs/en/1.1b2/reference/api/gino.ext.html b/docs/en/1.1b2/reference/api/gino.ext.html new file mode 100644 index 0000000..bcf694f --- /dev/null +++ b/docs/en/1.1b2/reference/api/gino.ext.html @@ -0,0 +1,227 @@ + + + + + + + + gino.ext package - GINO 1.1.0b2 documentation + + + + + + + + + + + +

+ + +

Tutorials

How-to Guides

Explanation

Reference

Reference
- API Reference
- Extensions
- History
+
API Reference
- gino package
+
Extensions
History

+ +

gino.ext package¶

Module contents¶

Namespace package for GINO extensions.

This namespace package didn’t use any of the 3 official solutions. Instead, +gino.ext adds a hook into sys.meta_path, and utilize the Entry points +to find the extensions.

Any GINO extension package should provide an entry point like this:

[gino.extensions]
+starlette = gino_starlette
+

+

So that the Python package gino_starlette will also be importable through +gino.ext.starlette.

+ + +

+ + + +
+ This work is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License. +

+ +

gino.ext package
- Module contents
+

+ + +

+ +

+ + +

+ Add your language here. +

+ +

+ +

+ + + + + + + + + + + \ No newline at end of file diff --git a/docs/en/1.1b2/reference/api/gino.html b/docs/en/1.1b2/reference/api/gino.html new file mode 100644 index 0000000..6075ac8 --- /dev/null +++ b/docs/en/1.1b2/reference/api/gino.html @@ -0,0 +1,280 @@ + + + + + + + + gino package - GINO 1.1.0b2 documentation + + + + + + + + + + + +

+ + +

Tutorials

How-to Guides

Explanation

Reference

Reference
- API Reference
- Extensions
- History
+
API Reference
- gino package
+
Extensions
History

+ +

gino package¶

Subpackages¶

gino.dialects package
- Submodules
  +
- Module contents
+
gino.ext package
- Module contents
+

Submodules¶

Module contents¶

+gino.create_engine(*args, **kwargs)¶

Shortcut for sqlalchemy.create_engine() with strategy="gino".

Changed in version 1.1: Added the bakery keyword argument, please see Bakery.

Changed in version 1.1: Added the prebake keyword argument to choose when to create the prepared +statements for the queries in the bakery:

Pre-bake immediately when connected to the database (default).
No pre-bake but create prepared statements lazily when needed for the first +time.

Note: prebake has no effect in aiomysql

+ +

+gino.get_version()¶: Get current GINO version.
+

+ +

+ + +

+ + + +
+ This work is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License. +

+ +

gino package
- Subpackages
- Submodules
- Module contents
+

+ + +

+ +

+ + +

+ Add your language here. +

+ +

+ +

+ + + + + + + + + + + \ No newline at end of file diff --git a/docs/en/1.1b2/reference/api/gino.json_support.html b/docs/en/1.1b2/reference/api/gino.json_support.html new file mode 100644 index 0000000..6c185ee --- /dev/null +++ b/docs/en/1.1b2/reference/api/gino.json_support.html @@ -0,0 +1,350 @@ + + + + + + + + gino.json_support module - GINO 1.1.0b2 documentation + + + + + + + + + + + +

+ + +

Tutorials

How-to Guides

Explanation

Reference

Reference
- API Reference
- Extensions
- History
+
API Reference
- gino package
+
Extensions
History

+ +

gino.json_support module¶

+class gino.json_support.ArrayProperty(default=None, prop_name='profile')¶

+decode(val)¶

+ +

+encode(val)¶

+ +

+class gino.json_support.BooleanProperty(default=None, prop_name='profile')¶

+decode(val)¶

+ +

+encode(val)¶

+ +

+make_expression(base_exp)¶

+ +

+class gino.json_support.DateTimeProperty(default=None, prop_name='profile')¶

+decode(val)¶

+ +

+encode(val)¶

+ +

+make_expression(base_exp)¶

+ +

+class gino.json_support.IntegerProperty(default=None, prop_name='profile')¶

+decode(val)¶

+ +

+encode(val)¶

+ +

+make_expression(base_exp)¶

+ +

+class gino.json_support.JSONProperty(default=None, prop_name='profile')¶

Bases: object

+decode(val)¶

+ +

+encode(val)¶

+ +

+get_profile(instance)¶

+ +

+make_expression(base_exp)¶

+ +

+reload(instance)¶

+ +

+save(instance, value=<object object>)¶

+ +

+class gino.json_support.ObjectProperty(default=None, prop_name='profile')¶

+decode(val)¶

+ +

+encode(val)¶

+ +

+class gino.json_support.StringProperty(default=None, prop_name='profile')¶

+make_expression(base_exp)¶

+ +

+ + +

+ + + +
+ This work is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License. +

+ +

gino.json_support module

+ + +

+ Add your language here. +

+ +

+ +

+ + + + + + + + + + + \ No newline at end of file diff --git a/docs/en/1.1b2/reference/api/gino.loader.html b/docs/en/1.1b2/reference/api/gino.loader.html new file mode 100644 index 0000000..f692fcd --- /dev/null +++ b/docs/en/1.1b2/reference/api/gino.loader.html @@ -0,0 +1,633 @@ + + + + + + + + gino.loader module - GINO 1.1.0b2 documentation + + + + + + + + + + + +

+ + +

Tutorials

How-to Guides

Explanation

Reference

Reference
- API Reference
- Extensions
- History
+
API Reference
- gino package
+
Extensions
History

+ +

gino.loader module¶

+class gino.loader.AliasLoader(alias, *columns, **extras)¶

Bases: gino.loader.ModelLoader

The same as ModelLoader, kept for compatibility.

+ +

+class gino.loader.CallableLoader(func)¶

Load the row by calling a specified function.

Parameters: func – A callable() taking 2 positional arguments (row, context) +that will be called in do_load(), returning the loaded result.
+

+do_load(row, context)¶

Interface used by GINO to run the loader.

The arguments are simply passed to the given function.

Parameters

row – A RowProxy instance.
context – A dict that is reused across all loaders in one query.

Returns

The result calling the given function, followed by True.

+ +

+class gino.loader.ColumnLoader(column)¶

Load a given column in the row.

Parameters: column – The column name as str, or a +Column instance to avoid name conflict.
+

+do_load(row, context)¶

Interface used by GINO to run the loader.

Parameters

row – A RowProxy instance.
context – Not used.

Returns

The value of the specified column, followed by True.

+ +

+class gino.loader.Loader¶

Bases: object

The abstract base class of loaders.

Loaders are used to load raw database rows into expected results. +GinoEngine will use the loader set on the loader value of +the execution_options(), for example:

from sqlalchemy import text, create_engine
+from gino.loader import ColumnLoader
+
+e = await create_engine("postgresql://localhost/gino", strategy="gino")
+q = text("SELECT now() as ts")
+loader = ColumnLoader("ts")
+ts = await e.first(q.execution_options(loader=loader))  # datetime
+

+

+do_load(row, context)¶

Interface used by GINO to run the loader.

Must be implemented in subclasses.

Parameters

row – A RowProxy instance.
context – A dict that is reused across all loaders in one query.

Returns

Any result that the loader is supposed to return, followed by a boolean +value indicating if the result is distinct.

+ +

+classmethod get(value)¶

Automatically create a loader based on the type of the given value.

+ ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

value type	loader type
`tuple`	`TupleLoader`
`callable()`	`CallableLoader`
`Column`, +`Label`	`ColumnLoader`
`Model`	`ModelLoader`
`Alias`	`AliasLoader`
`Loader`	as is
any other types	`ValueLoader`

Parameters: value – Any supported value above.
+
Returns: A loader instance.
+

+ +

+get_columns()¶

Generate a list of selectables from this loader.

This is an experimental feature, this method is supposed to be called by +query.

Returns: A list of SQLAlchemy selectables.
+

+ +

+get_from()¶

Generate a clause to be used in +select_from() from this loader.

This is an experimental feature, this method is supposed to be called by +query.

Returns: A FromClause instance, or None.
+

+ +

+property query¶

Generate a query from this loader.

This is an experimental feature, not all loaders support this.

Returns: A query instance with the loader execution option set to self.
+

+ +

+class gino.loader.ModelLoader(model, *columns, **extras)¶

A loader that loads a row into a GINO model instance.

This loader generates an instance of the given model type and fills the instance +with attributes according to the other given parameters:

Load each column attribute listed in the given columns positional arguments.
If columns is not given, all defined columns of the model will be loaded.
For each keyword argument, its value will be used to generate a loader using +Loader.get(), and the loaded value will be setattr() to the model +instance under the name of the key.

For example, the simplest select and load:

sqlalchemy.select([User]).execution_options(loader=ModelLoader(User))
+

+

Select only the name column, and still load it into model instances:

sqlalchemy.select(
+    [User.name]
+).execution_options(
+    loader=ModelLoader(User, User.name)
+)
+

+

This would also yield User instances, with all column attributes as None but +name.

Nest a ValueLoader:

sqlalchemy.select(
+    [User.name]
+).execution_options(
+    loader=ModelLoader(User, id=1)
+)
+

+

1 is then converted into a ValueLoader and mocked the id attribute +of all returned User instances as 1.

Nest another ModelLoader:

sqlalchemy.select(
+    [user.outerjoin(Company)]
+).execution_options(
+    loader=ModelLoader(User, company=Company)
+)
+

+

Parameters

model – A subclass of Model to instantiate.
columns – A list of Column or str to +load, default is all the columns in the model.
extras – Additional attributes to load on the model instance.

+distinct(*columns)¶

Configure this loader to reuse instances that have the same values of all the +give columns.

Parameters: columns – Preferably Column instances.
+
Returns: self for chaining.
+

+ +

+do_load(row, context)¶

Interface used by GINO to run the loader.

Parameters

row – A RowProxy instance.
context – A dict that is reused across all loaders in one query.

Returns

The model instance, followed by a boolean value indicating if the +result is distinct.

+ +

+get_columns()¶

Generate a list of selectables from this loader.

This is an experimental feature, this method is supposed to be called by +query.

Returns: A list of SQLAlchemy selectables.
+

+ +

+get_from()¶

Generate a clause to be used in +select_from() from this loader.

This is an experimental feature, this method is supposed to be called by +query.

Returns: A FromClause instance, or None.
+

+ +

+load(*columns, **extras)¶

Update the loader with new rules.

sqlalchemy.select(
+    [user.outerjoin(Company)]
+).execution_options(
+    loader=ModelLoader(User, company=Company.load('name'))
+)
+

+

Parameters

columns – If provided, replace the columns to load with the given ones.
extras – Update the loader with new extras.

Returns

self for chaining.

+ +

+none_as_none(enabled=True)¶: Deprecated method for compatibility, does nothing.
+

+ +

+on(on_clause)¶

Specify the on_clause for generating joined queries.

This is an experimental feature, used by get_from().

Parameters: on_clause – An expression to feed into +join().
+
Returns: self for chaining.
+

+ +

+class gino.loader.TupleLoader(values)¶

Load multiple values into a tuple.

Parameters: values – A tuple, each item is converted into a loader with +Loader.get().
+

+do_load(row, context)¶

Interface used by GINO to run the loader.

The arguments are simply passed to sub-loaders.

Parameters

row – A RowProxy instance.
context – A dict that is reused across all loaders in one query.

Returns

A tuple with loaded results from all sub-loaders, followed by +True.

+ +

+class gino.loader.ValueLoader(value)¶

A loader that always return the specified value.

Parameters: value – The value to return on load.
+

+do_load(row, context)¶

Interface used by GINO to run the loader.

Parameters

row – Not used.
context – Not used.

Returns

The given value, followed by True.

+ +

+ + +

+ + + +
+ This work is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License. +

+ +

gino.loader module

+ + +

+ Add your language here. +

+ +

+ +

+ + + + + + + + + + + \ No newline at end of file diff --git a/docs/en/1.1b2/reference/api/gino.schema.html b/docs/en/1.1b2/reference/api/gino.schema.html new file mode 100644 index 0000000..b2f0132 --- /dev/null +++ b/docs/en/1.1b2/reference/api/gino.schema.html @@ -0,0 +1,328 @@ + + + + + + + + gino.schema module - GINO 1.1.0b2 documentation + + + + + + + + + + + +

+ + +

Tutorials

How-to Guides

Explanation

Reference

Reference
- API Reference
- Extensions
- History
+
API Reference
- gino package
+
Extensions
History

+ +

gino.schema module¶

+class gino.schema.AsyncSchemaDropper(dialect, connection, checkfirst=False, tables=None, **kwargs)¶

Bases: gino.schema.AsyncVisitor, sqlalchemy.sql.ddl.SchemaDropper

+async visit_foreign_key_constraint(constraint)¶

+ +

+async visit_index(index)¶

+ +

+async visit_metadata(metadata)¶

+ +

+async visit_sequence(sequence, drop_ok=False)¶

+ +

+async visit_table(table, drop_ok=False, _is_metadata_operation=False)¶

+ +

+class gino.schema.AsyncSchemaGenerator(dialect, connection, checkfirst=False, tables=None, **kwargs)¶

Bases: gino.schema.AsyncVisitor, sqlalchemy.sql.ddl.SchemaGenerator

+async visit_foreign_key_constraint(constraint)¶

+ +

+async visit_index(index)¶

+ +

+async visit_metadata(metadata)¶

+ +

+async visit_sequence(sequence, create_ok=False)¶

+ +

+async visit_table(table, create_ok=False, include_foreign_key_constraints=None, _is_metadata_operation=False)¶

+ +

+class gino.schema.AsyncSchemaTypeMixin¶

Bases: object

+async create_async(bind=None, checkfirst=False)¶

+ +

+async drop_async(bind=None, checkfirst=False)¶

+ +

+class gino.schema.AsyncVisitor¶

Bases: object

+async traverse_single(obj, **kw)¶

+ +

+class gino.schema.GinoSchemaVisitor(item)¶

Bases: object

+async create(bind=None, *args, **kwargs)¶

+ +

+async create_all(bind=None, tables=None, checkfirst=True)¶

+ +

+async drop(bind=None, *args, **kwargs)¶

+ +

+async drop_all(bind=None, tables=None, checkfirst=True)¶

+ +

+gino.schema.patch_schema(db)¶

+ +

+ + +

+ + + +
+ This work is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License. +

+ +

gino.schema module

+ + +

+ Add your language here. +

+ +

+ +

+ + + + + + + + + + + \ No newline at end of file diff --git a/docs/en/1.1b2/reference/api/gino.strategies.html b/docs/en/1.1b2/reference/api/gino.strategies.html new file mode 100644 index 0000000..f4e78dd --- /dev/null +++ b/docs/en/1.1b2/reference/api/gino.strategies.html @@ -0,0 +1,236 @@ + + + + + + + + gino.strategies module - GINO 1.1.0b2 documentation + + + + + + + + + + + +

+ + +

Tutorials

How-to Guides

Explanation

Reference

Reference
- API Reference
- Extensions
- History
+
API Reference
- gino package
+
Extensions
History

+ +

gino.strategies module¶

+class gino.strategies.GinoStrategy¶

Bases: sqlalchemy.engine.strategies.EngineStrategy

A SQLAlchemy engine strategy for GINO.

This strategy is initialized automatically as gino is imported.

If sqlalchemy.create_engine() uses strategy="gino", it will return a +Coroutine, and treat URL prefix postgresql:// or +postgres:// as postgresql+asyncpg://.

+async create(name_or_url, loop=None, **kwargs)¶: Given arguments, returns a new Engine instance.
+

+ +

+engine_cls¶: alias of gino.engine.GinoEngine
+

+ +

+name = 'gino'¶

+ +

+ + +

+ + + +
+ This work is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License. +

+ +

gino.strategies module

+ + +

+ Add your language here. +

+ +

+ +

+ + + + + + + + + + + \ No newline at end of file diff --git a/docs/en/1.1b2/reference/api/gino.transaction.html b/docs/en/1.1b2/reference/api/gino.transaction.html new file mode 100644 index 0000000..8ccd16e --- /dev/null +++ b/docs/en/1.1b2/reference/api/gino.transaction.html @@ -0,0 +1,332 @@ + + + + + + + + gino.transaction module - GINO 1.1.0b2 documentation + + + + + + + + + + + +

+ + +

Tutorials

How-to Guides

Explanation

Reference

Reference
- API Reference
- Extensions
- History
+
API Reference
- gino package
+
Extensions
History

+ +

gino.transaction module¶

+class gino.transaction.GinoTransaction(conn, args, kwargs)¶

Bases: object

Represents an underlying database transaction and its connection, offering +methods to manage this transaction.

GinoTransaction is supposed to be created by either +gino.engine.GinoConnection.transaction(), or +gino.engine.GinoEngine.transaction(), or +gino.api.Gino.transaction(), shown as follows:

async with db.transaction() as tx:
+    ...
+
+async with engine.transaction() as tx:
+    ...
+
+async with conn.transaction() as tx:
+    ...
+
+tx = await conn.transaction()
+try:
+    ...
+    await tx.commit()
+except Exception:
+    await tx.rollback()
+    raise
+

+

async with db.transaction() as tx1:
+    async with db.transaction() as tx2:
+        async with db.transaction() as tx3:
+            tx2.raise_rollback()
+            # Won't reach here
+        # Won't reach here
+    # Continues here with tx1, with both tx2 and tx3 rolled back.
+
+    # For PostgreSQL, tx1 can still be committed successfully because
+    # tx2 and tx3 are just SAVEPOINTs in transaction tx1
+

+

Tip

The internal exception raised from raise_commit() and +raise_rollback() is a subclass of BaseException, so +normal try ... except Exception: can’t trap the commit or rollback.

+async commit()¶: Only available in manual mode: manually commit this transaction.
+

+ +

+property connection¶: Accesses to the GinoConnection of this +transaction. This is useful if when the transaction is started from +db or engine where the connection is implicitly acquired for +you together with the transaction.
+

+ +

+raise_commit()¶

async with db.transaction() as tx:
+    await user.update(age=64).apply()
+    tx.raise_commit()
+    await user.update(age=32).apply()  # won't reach here
+
+assert user.age == 64  # no exception raised before
+

+

+ +

+raise_rollback()¶

assert user.age == 64  # assumption
+
+async with db.transaction() as tx:
+    await user.update(age=32).apply()
+    tx.raise_rollback()
+    await user.update(age=128).apply()  # won't reach here
+
+assert user.age == 64  # no exception raised before
+

+

+ +

+property raw_transaction¶: Accesses to the underlying transaction object, whose type depends on +the dialect in use.
+

+ +

+async rollback()¶: Only available in manual mode: manually rollback this transaction.
+

+ +

+ + +

+ + + +
+ This work is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License. +

+ +

gino.transaction module

+ + +

+ Add your language here. +

+ +

+ +

+ + + + + + + + + + + \ No newline at end of file diff --git a/docs/en/1.1b2/reference/extensions.html b/docs/en/1.1b2/reference/extensions.html new file mode 100644 index 0000000..0d99f3c --- /dev/null +++ b/docs/en/1.1b2/reference/extensions.html @@ -0,0 +1,220 @@ + + + + + + + + Extensions - GINO 1.1.0b2 documentation + + + + + + + + + + + +

+ +

+ + + + + + + +

+ + + +

+ + HOME + + + CREDITS + + +

Tutorials

How-to Guides

Explanation

Reference

Reference
- API Reference
- Extensions
- History
+
API Reference
Extensions
- Sanic Support
- Starlette Support
- Tornado Support
+
History

+ +

Extensions¶

Sanic Support
- Work with Sanic
- Sanic Support
+
Starlette Support
- Work with Starlette
- Configuration
- Lazy Connection
+
Tornado Support

+ + +

+ + + +
+ This work is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License. +

+ +

Extensions

+ + +

+ Add your language here. +

+ +

+ +

+ + + + + + + + + + + \ No newline at end of file diff --git a/docs/en/1.1b2/reference/extensions/sanic.html b/docs/en/1.1b2/reference/extensions/sanic.html new file mode 100644 index 0000000..a904741 --- /dev/null +++ b/docs/en/1.1b2/reference/extensions/sanic.html @@ -0,0 +1,329 @@ + + + + + + + + Sanic Support - GINO 1.1.0b2 documentation + + + + + + + + + + + +

+ + +

Tutorials

How-to Guides

Explanation

Reference

Reference
- API Reference
- Extensions
- History
+
API Reference
Extensions
- Sanic Support
- Starlette Support
- Tornado Support
+
History

+ +

Sanic Support¶

THIS IS A WIP

Work with Sanic¶

Using the Sanic extension, the request handler acquires a lazy connection on each request, +and return the connection when the response finishes by default.

The lazy connection is actually established if necessary, i.e. just before first access to db.

This behavior is controlled by app.config.DB_USE_CONNECTION_FOR_REQUEST, which is True by default.

Supported configurations:

DB_HOST
DB_PORT
DB_USER
DB_PASSWORD
DB_DATABASE
DB_ECHO
DB_POOL_MIN_SIZE
DB_POOL_MAX_SIZE
DB_USE_CONNECTION_FOR_REQUEST
DB_KWARGS

An example server:

from sanic import Sanic
+from sanic.exceptions import abort
+from sanic.response import json
+from gino.ext.sanic import Gino
+
+app = Sanic()
+app.config.DB_HOST = 'localhost'
+app.config.DB_DATABASE = 'gino'
+db = Gino()
+db.init_app(app)
+
+
+class User(db.Model):
+    __tablename__ = 'users'
+
+    id = db.Column(db.BigInteger(), primary_key=True)
+    nickname = db.Column(db.Unicode())
+
+    def __repr__(self):
+        return '{}<{}>'.format(self.nickname, self.id)
+
+
+@app.route("/users/<user_id>")
+async def get_user(request, user_id):
+    if not user_id.isdigit():
+        abort(400, 'invalid user id')
+    user = await User.get_or_404(int(user_id))
+    return json({'name': user.nickname})
+
+
+if __name__ == '__main__':
+    app.run(debug=True)
+

+

Sanic Support¶

To integrate with Sanic, a few configurations needs to be set in +app.config (with default value though):

DB_HOST: if not set, localhost
DB_PORT: if not set, 5432
DB_USER: if not set, postgres
DB_PASSWORD: if not set, empty string
DB_DATABASE: if not set, postgres
DB_ECHO: if not set, False
DB_POOL_MIN_SIZE: if not set, 5
DB_POOL_MAX_SIZE: if not set, 10
DB_KWARGS; if not set, empty dictionary

An example:

from sanic import Sanic
+from gino.ext.sanic import Gino
+
+app = Sanic()
+app.config.DB_HOST = 'localhost'
+app.config.DB_USER = 'postgres'
+
+db = Gino()
+db.init_app(app)
+

+

await request['connection'].release()
+

+

Or if you prefer not to use the contextual lazy connection in certain handlers, +prefer explicitly manage the connection lifetime, you can always borrow a new +connection by setting reuse=False:

async with db.acquire(reuse=False):
+    # new connection context is created
+

+

Or if you prefer not to use the builtin request-scoped lazy connection at all, +you can simply turn it off:

app.config.DB_USE_CONNECTION_FOR_REQUEST = False
+

+

+ + +

+ + + +
+ This work is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License. +

+ +

Sanic Support
- Work with Sanic
- Sanic Support
+

+ + +

+ +

+ + +

+ Add your language here. +

+ +

+ +

+ + + + + + + + + + + \ No newline at end of file diff --git a/docs/en/1.1b2/reference/extensions/starlette.html b/docs/en/1.1b2/reference/extensions/starlette.html new file mode 100644 index 0000000..7faa63d --- /dev/null +++ b/docs/en/1.1b2/reference/extensions/starlette.html @@ -0,0 +1,326 @@ + + + + + + + + Starlette Support - GINO 1.1.0b2 documentation + + + + + + + + + + + +

+ + +

Tutorials

How-to Guides

Explanation

Reference

Reference
- API Reference
- Extensions
- History
+
API Reference
Extensions
- Sanic Support
- Starlette Support
- Tornado Support
+
History

+ +

Starlette Support¶

Work with Starlette¶

To use GINO with Starlette, the gino-starlette package should +be installed first:

pip install gino-starlette
+

+

Note

The gino-starlette package supports only GINO 1.0 or later. +Earlier versions of GINO like 0.8.x have built-in Starlette support.

This extension provides a Starlette middleware to setup and cleanup +database according to the configurations that passed in the kwargs +parameter.

The common usage looks like this:

from starlette.applications import Starlette
+from gino.ext.starlette import Gino
+
+app = Starlette()
+db = Gino(app, **kwargs)
+
+# Or with application factory
+app = Starlette()
+db = Gino(**kwargs)
+db.init_app(app)
+

+

Configuration¶

The config includes:

+ +++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

Name	Description	Default
`driver`	the database driver	`asyncpg`
`host`	database server host	`localhost`
`port`	database server port	`5432`
`user`	database server user	`postgres`
`password`	database server password	empty
`database`	database name	`postgres`
`dsn`	a SQLAlchemy database URL to create the engine, its existence will replace all previous connect arguments.	N/A
`pool_min_size`	the initial number of connections of the db pool.	N/A
`pool_max_size`	the maximum number of connections in the db pool.	N/A
`echo`	enable SQLAlchemy echo mode.	N/A
`ssl`	SSL context passed to `asyncpg.connect`	`None`
`use_connection_for_request`	flag to set up lazy connection for requests.	N/A
`kwargs`	other parameters passed to the specified dialects, like `asyncpg`. Unrecognized parameters will cause exceptions.	N/A

Lazy Connection¶

await request['connection'].release(permanent=False)
+

+

+ + +

+ + + +
+ This work is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License. +

+ +

Starlette Support
- Work with Starlette
- Configuration
- Lazy Connection
+

+ + +

+ +

+ + +

+ Add your language here. +

+ +

+ +

+ + + + + + + + + + + \ No newline at end of file diff --git a/docs/en/1.1b2/reference/extensions/tornado.html b/docs/en/1.1b2/reference/extensions/tornado.html new file mode 100644 index 0000000..9e26b7a --- /dev/null +++ b/docs/en/1.1b2/reference/extensions/tornado.html @@ -0,0 +1,208 @@ + + + + + + + + Tornado Support - GINO 1.1.0b2 documentation + + + + + + + + + + + +

+ + +

Tutorials

How-to Guides

Explanation

Reference

Reference
- API Reference
- Extensions
- History
+
API Reference
Extensions
- Sanic Support
- Starlette Support
- Tornado Support
+
History

+ +

Tornado Support¶

THIS IS A WIP

+ + +

+ + + +
+ This work is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License. +

+ +

Tornado Support

+ + +

+ Add your language here. +

+ +

+ +

+ + + + + + + + + + + \ No newline at end of file diff --git a/docs/en/1.1b2/reference/history.html b/docs/en/1.1b2/reference/history.html new file mode 100644 index 0000000..00b4efc --- /dev/null +++ b/docs/en/1.1b2/reference/history.html @@ -0,0 +1,918 @@ + + + + + + + + History - GINO 1.1.0b2 documentation + + + + + + + + + + + +

+ +

+ + + + + + + +

+ + + +

+ + HOME + + + CREDITS + + +

Tutorials

How-to Guides

Explanation

Reference

Reference
- API Reference
- Extensions
- History
+
API Reference
Extensions
History

+ +

History¶

GINO 1.1¶

1.1.0 (pending)¶

Added baked query feature (#478 #659 #667)
Added Query.gino.execution_options shortcut (#659)
Added @db.declared_attr(with_table=True) (#659)

GINO 1.0¶

Migrating to GINO 1.0¶

GINO 1.0 moved the built-in Web framework extensions into separate PyPI +packages. If you’re using one of them, you should install GINO 1.0 with extras:

+ ++++ + + + + + + + + + + + + + + + + + + + + + + +

Extension Module	Installation in GINO 1.0
`gino.ext.starlette`	`pip install gino[starlette]`
`gino.ext.aiohttp`	`pip install gino[aiohttp]`
`gino.ext.sanic`	`pip install gino[sanic]`
`gino.ext.tornado`	`pip install gino[tornado]`
`gino.ext.quart`	`pip install gino[quart]`

The new extension packages are backward-compatible, so there’s no need to +update the import statements. For example, this will still work in GINO 1.0 if +you installed gino[starlette]:

from gino.ext.starlette import Gino
+

+

Source files are now located under src directory.
The src dist on PyPI does not include tests, docs and some other files due to +a limitation of Poetry.

1.0.1 (2020-06-08)¶

Fixed dependency version range (SQLAlchemy >=1.2.16, <1.4)
Updated docs (Including contribution by Galden in #660, and Iuliia Volkova in #672)
Multiple JSON property fixes (#661 #662 #695)
Fixed extension typing issue (#673 #674)
Fixed model override behavior (#694)
Fixed multiple JSON profiles issue (Contributed by Roman Averchenkov in #693 #696)

1.0.0 (2020-04-26)¶

Switched to Poetry for package and dependency management.
[Breaking] Moved built-in extension modules to separate PyPI packages.
Switched to src layout.
Switched to black code style.
Better documentation.
[Breaking] none_as_none() is now always enabled.
Added representation method for engine.
Protected the URL instance fed to set_bind() from manipulation.
Replaced some assert with AssertionError (#258 #655)

GINO 0.8¶

This is also version 1.0 release candidate.

Migrating to GINO 0.8¶

1. contextvars¶

There is nothing to worry about in Python 3.7.

2. none_as_none¶

This is especially applicable to relationship sub-loaders - if the sub-loader +found it all NULL, no instance will be set to parent instance. For +example:

child = await Child.load(parent=Parent).query.gino.first()
+

+

Please note, it is deprecated to disable none_as_none, and disabling will +be removed in GINO 1.0.

0.8.7 (2020-04-19)¶

Improved error handling when attribute names collide (Contributed by Reskov in #637 #638)
Fixed with_bind usability in aiohttp extension (#518)

0.8.6 (2020-02-10)¶

Fixed JSONPathType bind processor for asyncpg (#609)
Allowed for primary keys with different names from the database columns (Contributed by Tiago Requeijo in #599 #600)
Allowed to use simple callable instead of property for one-2-many loading (Contributed by Olexiy in #629)
Added distinct() to Alias (#628)

0.8.5 (2019-11-19)¶

Improved support for __tablename__ in declared_attr (Contributed by Roald Storm in #592)

0.8.4 (2019-11-09)¶

Better loader support for models in subqueries (#573 #585)
Allowed __tablename__ to be a declared_attr (#579 #582)
Fixed Sanic 19.9.0 compatibility (#569)
Added one() and one_or_none() (Contributed by Ilaï Deutel in #577)
Improved Starleet extension compatibility (Contributed by Jim O’Brien in #538)
Fixed Starlette connection release during exceptions issue (Contributed by qulaz in #533)
Fixed server event compatibility with Sanic 19.6.2 (Contributed by Julio Lacerda in #520)
Fixed Grammar (Contributed by Simeon J Morgan in #504)

0.8.3 (2019-06-06)¶

Fixed deprecated warnings in asyncpg dialect and aiohttp (#425)
Customizable db attribute name in aiohttp app instance (#457)
Added Starlette support (#486)

0.8.2 (2019-03-07)¶

Added exception for unknown JSON properties (#406 #408)
Supported Quart 0.7 (#411)
Accepted kwargs for db init in extensions (#407 #427)
Added custom config parameter to aiohttp middleware (Contributed by Michał Dziewulski in #440)
Added NullPool (#437 #441)
Unpinned dependency versions (#447)
Added support for SQLAlchemy 1.3 (#433 #451)

0.8.1 (2018-12-08)¶

Alias supported Label (#365)
Docs update (#308, 4c59ad, #401 by Pascal van Kooten)
Version requirement for SQLAlchemy is updated to >=1.2 (#378 #382)
Added option for SSL in aiohttp extension (Contributed by Martin Zaťko in #387 #393) +* And all other extensions (#395)
Supported Tornado 5 (#396, also thanks to Vladimir Goncharov)
Fixed custom JSON/JSONB type support (#402 #403)

(Most fixes done by Tony Wang)

0.8.0 (2018-10-16)¶

Welcome Tony Wang to the maintenance team (#335)
Allowed custom column names (#261 #297)
Allowed column instance in model.load() (Contributed by Jekel in #323)
[Breaking] Upgraded to aiocontextvars 0.2.0 (#333)
Fixed bug that the same empty stack is shared between sub-tasks (#313 #334)
[Breaking] Made none_as_none() the default behavior (#351)
Bug fixes and docs update

GINO 0.7¶

This is also version 1.0 beta 3.

0.7.7 (2018-12-08)¶

Backported fix for custom JSON/JSONB type support (#402 #403)

0.7.6 (2018-08-26)¶

Updated library support (Contributed by Tony Wang in #275 #309)
Added none_as_none() (#281 #282)
Added ARRAY alias in asyncpg dialect module (Contributed by Mykyta Holubakha in #289)
Added Model.lookup() to prevent updating whole table without primary key (#287 #288)
Added DB_ECHO in extension options (Contributed by Mykyta Holubakha in #298)
Fixed broken JSON/JSONB result processor since 0.5.8 (Contributed by Tony Wang in #291 #305)
Removed bad rollback after a failing commit (Contributed by Tony Wang in #302 #304)
Fixed to raise UninitializedError if bind is None (Contributed by Tony Wang in #307 #310)

0.7.5 (2018-07-26)¶

Added friendly error message when using abstract models by mistake (#224)
Supported Python 3.7 (Contributed by Tony Wang in #265)
Updated documentation
Fixed a bug in TupleLoader (Contributed by Pavol Vargovcik in #279 #280)

0.7.4 (2018-06-10)¶

Added aiocontextvars as required dependency required for Python 3.5 and 3.6 (#228)
Added Quart support (#213)
Fixed Tornado options parsing (#231)
Improved coding style and test coverage

0.7.3 (2018-05-19)¶

Fix for failing binary type (#225)

0.7.2 (2018-05-15)¶

Added prepared statement support (#14)
Added dsn in extension config (Contributed by Yurii Shtrikker in #215)

0.7.1 (2018-05-03)¶

Added support for inline model constraints (Contributed by Kinware in #198)
Added docs and tests for using SSL (#202)
Added declared_attr (#204)
Allowed ModelLoader passively load partial model (#216)

0.7.0 (2018-04-18)¶

Added Python 3.5 support (#187)
Added support to use dict as ident for Model.get (#192)
Added result loader (partial relationship support) (#13)
Added documentation on relationship and transaction (#146)

GINO 0.6¶

This is also version 1.0 beta 2.

Migrating to GINO 0.6¶

1. Task Local¶

We created a new Python package aiocontextvars from previous local.py. If +you made use of the task local features, you should install this package.

There is no gino.get_local() and gino.reset_local() relevant in +aiocontextvars. The similar thing is aiocontextvars.ContextVar instance +through its get(), set() and delete() methods.

Previous gino.is_local_root() is now +not aiocontextvars.Context.current().inherited.

2. Engine¶

GINO 0.6 hides asyncpg.Pool behind the new SQLAlchemy-alike +gino.GinoEngine. Instead of doing this in 0.5:

async with db.create_pool('postgresql://...') as pool:
+    # your code here
+

+

You should change it to this in 0.6:

async with db.with_bind('postgresql://...') as engine:
+    # your code here
+

+

This equals to:

engine = await gino.create_engine('postgresql://...')
+db.bind = engine
+try:
+    # your code here
+finally:
+    db.bind = None
+    await engine.close()
+

+

Or:

engine = await db.set_bind('postgresql://...')
+try:
+    # your code here
+finally:
+    await db.pop_bind().close()
+

+

Or even this:

db = await gino.Gino('postgresql://...')
+try:
+    # your code here
+finally:
+    await db.pop_bind().close()
+

+

Choose whichever suits you the best.

Obviously GinoEngine doesn’t provide asyncpg.Pool methods directly any +longer, but you can get the underlying asyncpg.Pool object through +engine.raw_pool property.

GinoPool.get_current_connection() is now changed to current_connection +property on GinoEngine instances to support multiple engines.

GinoPool.execution_option is gone, instead update_execution_options() +on GinoEngine instance is available.

GinoPool().metadata is gone, dialect is still available.

GinoPool.release() is removed in GinoEngine and Gino, the +release() method on GinoConnection object should be used instead.

These methods exist both in 0.5 GinoPool and 0.6 GinoEngine: +close(), acquire(), all(), first(), scalar(), status().

3. GinoConnection¶

Similarly, GinoConnection in 0.6 is no longer a subclass of +asyncpg.Connection, instead it has a asyncpg.Connection instance, +accessable through GinoConnection.raw_connection property.

GinoConnection.metadata is deleted in 0.6, while dialect remained.

GinoConnection.execution_options() is changed from a mutable dict in 0.5 to +a method returning a copy of current connection with the new options, the same +as SQLAlchemy behavior.

And all(), first(), scalar(), status(), iterate(), +transaction() remained in 0.6.

4. Query API¶

5. Transaction¶

Transaction interface is rewritten. Now in 0.6, a GinoTransaction object is +provided consistently from all 3 methods:

async with db.transaction() as tx:
+    # within transaction
+
+async with engine.transaction() as tx:
+    # within transaction
+
+async with engine.acquire() as conn:
+    async with conn.transaction() as tx:
+        # within transaction
+

+

And different usage with await:

tx = await db.transaction()
+try:
+    # within transaction
+    await tx.commit()
+except:
+    await tx.rollback()
+    raise
+

+

0.6.6 (2018-05-18)¶

Backported a fix for failing binary type (#225)

0.6.5 (2018-04-18)¶

Abandoned 0.6.4 and keep 0.6.x stable
Backported doc for transaction

0.6.4 (2018-04-16)¶

Abandoned version, please use 0.7.0 instead.

0.6.3 (2018-04-08)¶

Added aiohttp support
Added support for calling create() on model instances (Contributed by Kinware in #178 #180)
Fixed get() by string, and misc environment issues (Contributed by Tony Wang in #191 193 #183 #184)

0.6.2 (2018-03-24)¶

Fixed SQLAlchemy prefetch issue (#141)
Fixed issue that mixin class on Model not working (#174)
Added more documentation (Thanks Olaf Conradi for reviewing)

0.6.1 (2018-03-18)¶

Fixed create and drop for Enum type (#160)
A bit more documentation (#159)

0.6.0 (2018-03-14)¶

[Breaking] API Refactored, Pool replaced with Engine
+
- New API Engine replaced asyncpg Pool (#59)
- Supported different dialects, theoretically
- Used aiocontextvars instead of builtin task local (#89)
+
[Breaking] Fixed query API with multiparams (executemany) to return correctly (#20)
[Breaking] The query methods no longer accept the parameter bind
[Breaking] Gino no longer exposes postgresql types
Added echo on engine (#142)
Added tests to cover 80% of code
Added gino extension on SchemaItem for create_all and so on (#76 #106)
Added gino extension on model classes for create() or drop()
Added _update_request_cls on CRUDModel (#147)
Rewrote the documentation (#146)

GINO 0.5¶

This is also version 1.0 beta 1.

0.5.8 (2018-02-14)¶

Preparing for 0.6.0 which will be a breaking release
Fixed wrong value of Enum in creation (Contributed by Sergey Kovalev in #126)

0.5.7 (2017-11-24)¶

This is an emergency fix for 0.5.6.

Fixed broken lazy connection (Contributed by Ádám Barancsuk in #114)
Added Model.outerjoin

0.5.6 (2017-11-23)¶

Changed to use unnamed statement when possible (#80 #90)
Added more example (Contributed by Kentoseth in #109)
Added Model.join and made Model selectable (Contributed by Ádám Barancsuk in #112 #113)

0.5.5 (2017-10-18)¶

Ensured clean connection if transaction acquire fails (Contributed by Vladimir Goncharov in #87)
Added ability to reset local storage (#84)
Fixed bug in JSON property update
Added update chaining feature

0.5.4 (2017-10-04)¶

Updated example (Contributed by Kinware in #75)
Added Model.insert (Contributed by Neal Wang in #63)
Fixed issue that non-lazy acquiring fails dirty (#79)

0.5.3 (2017-09-23)¶

Fixed no module named cutils error (Contributed by Vladimir Goncharov in #73)

0.5.2 (2017-09-10)¶

Added missing driver name on dialect (#67)
Fixed dialect to support native decimal type (#67)

0.5.1 (2017-09-09)¶

This is an emergency fix for 0.5.0.

Reverted the extension, back to pure Python (#60)
Used SQLAlchemy RowProxy
Added first_or_404
Fixed bug that GinoPool cannot be inherited

0.5.0 (2017-09-03)¶

[Breaking] Internal refactor: extracted and isolated a few modules, partially rewritten
+
- Extracted CRUD operations
- Core operations are moved to dialect and execution context
- Removed guess_model, switched to explicit execution options
- Turned timeout parameter to an execution option
- Extracted pool, connection and api from asyncpg_delegate
+
Added support for SQLAlchemy execution options, and a few custom options
[Breaking] Made Model.select return rows by default (#39)
Moved get_or_404 to extensions (#38)
Added iterator on model classes (#43)
Added Tornado extension (Contributed by Vladimir Goncharov)
Added Model.to_dict (#47)
Added an extension module to update asyncpg.Record with processed results

Early Development Releases¶

Considered as alpha releases.

0.4.1 (2017-08-20)¶

Support select on model instance

0.4.0 (2017-08-15)¶

Made get_or_404 more friendly when Sanic is missing (Contributed by Neal Wang in #23 #31)
Delegated sqlalchemy.__all__ (Contributed by Neal Wang in #10 #33)
[Breaking] Rewrote JSON/JSONB support (#29)
Added lazy parameter on db.acquire (Contributed by Binghan Li in #32)
Added Sanic integration (Contributed by Binghan Li, Tony Wang in #30 #32 #34)
Fixed iterate API to be compatible with asyncpg (#32)
Unified exceptions
[Breaking] Changed update API (#29)
Bug fixes

0.3.0 (2017-08-07)¶

Supported __table_args__ (#12)
Introduced task local to manage connection in context (#19)
Added query.gino extension for in-place execution
Refreshed README (#3)
Adopted PEP 487 (Contributed by Tony Wang in #17 #27)
Used weakref on __model__ of table and query (Contributed by Tony Wang)
Delegated asyncpg timeout parameter (Contributed by Neal Wang in #16 #22)

0.2.3 (2017-08-04)¶

Supported any primary key (Contributed by Tony Wang in #11)

0.2.2 (2017-08-02)¶

Supported SQLAlchemy result processor
Added rich support on JSON/JSONB
Bug fixes

0.2.1 (2017-07-28)¶

Added update and delete API

0.2.0 (2017-07-28)¶

Changed API, no longer reuses asyncpg API

0.1.1 (2017-07-25)¶

Added db.bind
API changed: parameter conn renamed to optional bind
Delegated asyncpg Pool with db.create_pool
Internal enhancement and bug fixes

0.1.0 (2017-07-21)¶

First release on PyPI.

+ + +

+ + + +
+ This work is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License. +

+ +

History
- GINO 1.1
  - 1.1.0 (pending)
  +
- GINO 1.0
  +
- GINO 0.8
  - Migrating to GINO 0.8
    - 1. contextvars
    - 2. none_as_none
    +
  - 0.8.7 (2020-04-19)
  - 0.8.6 (2020-02-10)
  - 0.8.5 (2019-11-19)
  - 0.8.4 (2019-11-09)
  - 0.8.3 (2019-06-06)
  - 0.8.2 (2019-03-07)
  - 0.8.1 (2018-12-08)
  - 0.8.0 (2018-10-16)
  +
- GINO 0.7
  +
- GINO 0.6
  - Migrating to GINO 0.6
    - 1. Task Local
    - 2. Engine
    - 3. GinoConnection
    - 4. Query API
    - 5. Transaction
    +
  - 0.6.6 (2018-05-18)
  - 0.6.5 (2018-04-18)
  - 0.6.4 (2018-04-16)
  - 0.6.3 (2018-04-08)
  - 0.6.2 (2018-03-24)
  - 0.6.1 (2018-03-18)
  - 0.6.0 (2018-03-14)
  +
- GINO 0.5
  +
- Early Development Releases
  +
+

+ + +

+ +

+ + +

+ Add your language here. +

+ +

+ +

+ + + + + + + + + + + \ No newline at end of file diff --git a/docs/en/1.1b2/search.html b/docs/en/1.1b2/search.html new file mode 100644 index 0000000..2500d6c --- /dev/null +++ b/docs/en/1.1b2/search.html @@ -0,0 +1 @@ +

search.html

\ No newline at end of file diff --git a/docs/en/1.1b2/searchindex.js b/docs/en/1.1b2/searchindex.js new file mode 100644 index 0000000..37de280 --- /dev/null +++ b/docs/en/1.1b2/searchindex.js @@ -0,0 +1 @@ +Search.setIndex({docnames:["explanation","explanation/async","explanation/engine","explanation/sa20","explanation/why","how-to","how-to/alembic","how-to/bakery","how-to/contributing","how-to/crud","how-to/faq","how-to/json-props","how-to/loaders","how-to/pool","how-to/schema","how-to/transaction","index","reference","reference/api","reference/api/gino","reference/api/gino.aiocontextvars","reference/api/gino.api","reference/api/gino.bakery","reference/api/gino.crud","reference/api/gino.declarative","reference/api/gino.dialects","reference/api/gino.dialects.aiomysql","reference/api/gino.dialects.asyncpg","reference/api/gino.dialects.base","reference/api/gino.engine","reference/api/gino.exceptions","reference/api/gino.ext","reference/api/gino.json_support","reference/api/gino.loader","reference/api/gino.schema","reference/api/gino.strategies","reference/api/gino.transaction","reference/extensions","reference/extensions/sanic","reference/extensions/starlette","reference/extensions/tornado","reference/history","tutorials","tutorials/announcement","tutorials/fastapi","tutorials/tutorial"],envversion:{"sphinx.domains.c":2,"sphinx.domains.changeset":1,"sphinx.domains.citation":1,"sphinx.domains.cpp":3,"sphinx.domains.index":1,"sphinx.domains.javascript":2,"sphinx.domains.math":2,"sphinx.domains.python":2,"sphinx.domains.rst":2,"sphinx.domains.std":1,"sphinx.ext.intersphinx":1,sphinx:56},filenames:["explanation.rst","explanation/async.rst","explanation/engine.rst","explanation/sa20.rst","explanation/why.rst","how-to.rst","how-to/alembic.rst","how-to/bakery.rst","how-to/contributing.rst","how-to/crud.rst","how-to/faq.rst","how-to/json-props.rst","how-to/loaders.rst","how-to/pool.rst","how-to/schema.rst","how-to/transaction.rst","index.rst","reference.rst","reference/api.rst","reference/api/gino.rst","reference/api/gino.aiocontextvars.rst","reference/api/gino.api.rst","reference/api/gino.bakery.rst","reference/api/gino.crud.rst","reference/api/gino.declarative.rst","reference/api/gino.dialects.rst","reference/api/gino.dialects.aiomysql.rst","reference/api/gino.dialects.asyncpg.rst","reference/api/gino.dialects.base.rst","reference/api/gino.engine.rst","reference/api/gino.exceptions.rst","reference/api/gino.ext.rst","reference/api/gino.json_support.rst","reference/api/gino.loader.rst","reference/api/gino.schema.rst","reference/api/gino.strategies.rst","reference/api/gino.transaction.rst","reference/extensions.rst","reference/extensions/sanic.rst","reference/extensions/starlette.rst","reference/extensions/tornado.rst","reference/history.rst","tutorials.rst","tutorials/announcement.rst","tutorials/fastapi.rst","tutorials/tutorial.rst"],objects:{"":{gino:[19,0,0,"-"]},"gino.aiocontextvars":{patch_asyncio:[20,1,1,""]},"gino.api":{Gino:[21,2,1,""],GinoExecutor:[21,2,1,""]},"gino.api.Gino":{Model:[21,3,1,""],acquire:[21,3,1,""],all:[21,3,1,""],bake:[21,3,1,""],bakery:[21,3,1,""],bind:[21,3,1,""],compile:[21,3,1,""],first:[21,3,1,""],iterate:[21,3,1,""],model_base_classes:[21,4,1,""],no_delegate:[21,4,1,""],one:[21,3,1,""],one_or_none:[21,3,1,""],pop_bind:[21,3,1,""],query_executor:[21,4,1,""],scalar:[21,3,1,""],schema_visitor:[21,4,1,""],set_bind:[21,3,1,""],status:[21,3,1,""],transaction:[21,3,1,""],with_bind:[21,3,1,""]},"gino.api.GinoExecutor":{all:[21,3,1,""],execution_options:[21,3,1,""],first:[21,3,1,""],iterate:[21,3,1,""],load:[21,3,1,""],model:[21,3,1,""],one:[21,3,1,""],one_or_none:[21,3,1,""],query:[21,3,1,""],return_model:[21,3,1,""],scalar:[21,3,1,""],status:[21,3,1,""],timeout:[21,3,1,""]},"gino.bakery":{BakedQuery:[22,2,1,""],Bakery:[22,2,1,""]},"gino.bakery.BakedQuery":{bind:[22,3,1,""],compiled_sql:[22,3,1,""],execution_options:[22,3,1,""],get:[22,3,1,""],query:[22,3,1,""],sql:[22,3,1,""]},"gino.bakery.Bakery":{bake:[22,3,1,""],query_cls:[22,4,1,""]},"gino.crud":{Alias:[23,2,1,""],CRUDModel:[23,2,1,""],QueryModel:[23,2,1,""],UpdateRequest:[23,2,1,""]},"gino.crud.Alias":{distinct:[23,3,1,""],load:[23,3,1,""],on:[23,3,1,""]},"gino.crud.CRUDModel":{"delete":[23,4,1,""],alias:[23,3,1,""],append_where_primary_key:[23,3,1,""],create:[23,3,1,""],distinct:[23,3,1,""],get:[23,3,1,""],in_query:[23,3,1,""],load:[23,3,1,""],lookup:[23,3,1,""],none_as_none:[23,3,1,""],on:[23,3,1,""],query:[23,4,1,""],select:[23,3,1,""],to_dict:[23,3,1,""],update:[23,4,1,""]},"gino.crud.UpdateRequest":{apply:[23,3,1,""],update:[23,3,1,""]},"gino.declarative":{ColumnAttribute:[24,2,1,""],InvertDict:[24,2,1,""],Model:[24,2,1,""],declarative_base:[24,1,1,""],declared_attr:[24,1,1,""]},"gino.declarative.InvertDict":{invert_get:[24,3,1,""]},"gino.dialects":{aiomysql:[26,0,0,"-"],asyncpg:[27,0,0,"-"],base:[28,0,0,"-"]},"gino.dialects.aiomysql":{AiomysqlDBAPI:[26,2,1,""],AiomysqlDialect:[26,2,1,""],AiomysqlExecutionContext:[26,2,1,""],AiomysqlIterator:[26,2,1,""],AsyncEnum:[26,2,1,""],DBAPICursor:[26,2,1,""],GinoNullType:[26,2,1,""],Pool:[26,2,1,""],Transaction:[26,2,1,""]},"gino.dialects.aiomysql.AiomysqlDBAPI":{paramstyle:[26,4,1,""]},"gino.dialects.aiomysql.AiomysqlDialect":{colspecs:[26,4,1,""],cursor_cls:[26,4,1,""],dbapi_class:[26,4,1,""],driver:[26,4,1,""],execution_ctx_cls:[26,4,1,""],get_isolation_level:[26,3,1,""],has_table:[26,3,1,""],init_kwargs:[26,4,1,""],init_pool:[26,3,1,""],on_connect:[26,3,1,""],postfetch_lastrowid:[26,4,1,""],set_isolation_level:[26,3,1,""],statement_compiler:[26,4,1,""],support_prepare:[26,4,1,""],support_returning:[26,4,1,""],supports_native_decimal:[26,4,1,""],transaction:[26,3,1,""]},"gino.dialects.aiomysql.AiomysqlExecutionContext":{get_affected_rows:[26,3,1,""],get_lastrowid:[26,3,1,""]},"gino.dialects.aiomysql.AiomysqlIterator":{forward:[26,3,1,""],many:[26,3,1,""],next:[26,3,1,""]},"gino.dialects.aiomysql.AsyncEnum":{create_async:[26,3,1,""],drop_async:[26,3,1,""]},"gino.dialects.aiomysql.DBAPICursor":{async_execute:[26,3,1,""],description:[26,3,1,""],execute_baked:[26,3,1,""],get_statusmsg:[26,3,1,""],iterate:[26,3,1,""],prepare:[26,3,1,""]},"gino.dialects.aiomysql.GinoNullType":{result_processor:[26,3,1,""]},"gino.dialects.aiomysql.Pool":{acquire:[26,3,1,""],close:[26,3,1,""],raw_pool:[26,3,1,""],release:[26,3,1,""],repr:[26,3,1,""]},"gino.dialects.aiomysql.Transaction":{begin:[26,3,1,""],commit:[26,3,1,""],raw_transaction:[26,3,1,""],rollback:[26,3,1,""]},"gino.dialects.asyncpg":{AsyncEnum:[27,2,1,""],AsyncpgCompiler:[27,2,1,""],AsyncpgCursor:[27,2,1,""],AsyncpgDBAPI:[27,2,1,""],AsyncpgDialect:[27,2,1,""],AsyncpgExecutionContext:[27,2,1,""],AsyncpgIterator:[27,2,1,""],AsyncpgJSONPathType:[27,2,1,""],DBAPICursor:[27,2,1,""],GinoNullType:[27,2,1,""],NullPool:[27,2,1,""],Pool:[27,2,1,""],PreparedStatement:[27,2,1,""],Transaction:[27,2,1,""]},"gino.dialects.asyncpg.AsyncEnum":{create_async:[27,3,1,""],drop_async:[27,3,1,""]},"gino.dialects.asyncpg.AsyncpgCompiler":{bindtemplate:[27,3,1,""]},"gino.dialects.asyncpg.AsyncpgCursor":{forward:[27,3,1,""],many:[27,3,1,""],next:[27,3,1,""]},"gino.dialects.asyncpg.AsyncpgDBAPI":{Error:[27,4,1,""]},"gino.dialects.asyncpg.AsyncpgDialect":{colspecs:[27,4,1,""],cursor_cls:[27,4,1,""],dbapi_class:[27,4,1,""],driver:[27,4,1,""],execution_ctx_cls:[27,4,1,""],get_isolation_level:[27,3,1,""],has_schema:[27,3,1,""],has_sequence:[27,3,1,""],has_table:[27,3,1,""],has_type:[27,3,1,""],init_kwargs:[27,4,1,""],init_pool:[27,3,1,""],on_connect:[27,3,1,""],set_isolation_level:[27,3,1,""],statement_compiler:[27,4,1,""],supports_native_decimal:[27,4,1,""],transaction:[27,3,1,""]},"gino.dialects.asyncpg.AsyncpgJSONPathType":{bind_processor:[27,3,1,""]},"gino.dialects.asyncpg.DBAPICursor":{async_execute:[27,3,1,""],description:[27,3,1,""],execute_baked:[27,3,1,""],get_statusmsg:[27,3,1,""],prepare:[27,3,1,""]},"gino.dialects.asyncpg.GinoNullType":{result_processor:[27,3,1,""]},"gino.dialects.asyncpg.NullPool":{acquire:[27,3,1,""],close:[27,3,1,""],raw_pool:[27,3,1,""],release:[27,3,1,""],repr:[27,3,1,""]},"gino.dialects.asyncpg.Pool":{acquire:[27,3,1,""],close:[27,3,1,""],raw_pool:[27,3,1,""],release:[27,3,1,""],repr:[27,3,1,""]},"gino.dialects.asyncpg.Transaction":{begin:[27,3,1,""],commit:[27,3,1,""],raw_transaction:[27,3,1,""],rollback:[27,3,1,""]},"gino.dialects.base":{AsyncDialectMixin:[28,2,1,""],BaseDBAPI:[28,2,1,""],Cursor:[28,2,1,""],DBAPICursor:[28,2,1,""],ExecutionContextOverride:[28,2,1,""],Pool:[28,2,1,""],PreparedStatement:[28,2,1,""],Transaction:[28,2,1,""]},"gino.dialects.base.AsyncDialectMixin":{compile:[28,3,1,""],cursor_cls:[28,4,1,""],dbapi:[28,3,1,""],dbapi_class:[28,4,1,""],init_pool:[28,3,1,""],support_prepare:[28,4,1,""],support_returning:[28,4,1,""],transaction:[28,3,1,""]},"gino.dialects.base.BaseDBAPI":{Binary:[28,3,1,""],Error:[28,4,1,""],paramstyle:[28,4,1,""]},"gino.dialects.base.Cursor":{forward:[28,3,1,""],many:[28,3,1,""],next:[28,3,1,""]},"gino.dialects.base.DBAPICursor":{async_execute:[28,3,1,""],description:[28,3,1,""],execute:[28,3,1,""],execute_baked:[28,3,1,""],executemany:[28,3,1,""],get_statusmsg:[28,3,1,""],prepare:[28,3,1,""]},"gino.dialects.base.ExecutionContextOverride":{baked_query:[28,4,1,""],get_affected_rows:[28,3,1,""],get_lastrowid:[28,3,1,""],get_result_proxy:[28,3,1,""],loader:[28,4,1,""],model:[28,4,1,""],process_rows:[28,3,1,""],return_model:[28,4,1,""],timeout:[28,4,1,""]},"gino.dialects.base.Pool":{acquire:[28,3,1,""],close:[28,3,1,""],raw_pool:[28,3,1,""],release:[28,3,1,""],repr:[28,3,1,""]},"gino.dialects.base.PreparedStatement":{all:[28,3,1,""],first:[28,3,1,""],iterate:[28,3,1,""],scalar:[28,3,1,""],status:[28,3,1,""]},"gino.dialects.base.Transaction":{begin:[28,3,1,""],commit:[28,3,1,""],raw_transaction:[28,3,1,""],rollback:[28,3,1,""]},"gino.engine":{GinoConnection:[29,2,1,""],GinoEngine:[29,2,1,""]},"gino.engine.GinoConnection":{all:[29,3,1,""],dialect:[29,3,1,""],execution_options:[29,3,1,""],first:[29,3,1,""],get_raw_connection:[29,3,1,""],iterate:[29,3,1,""],one:[29,3,1,""],one_or_none:[29,3,1,""],prepare:[29,3,1,""],raw_connection:[29,3,1,""],release:[29,3,1,""],scalar:[29,3,1,""],schema_for_object:[29,4,1,""],status:[29,3,1,""],transaction:[29,3,1,""]},"gino.engine.GinoEngine":{acquire:[29,3,1,""],all:[29,3,1,""],close:[29,3,1,""],compile:[29,3,1,""],connection_cls:[29,4,1,""],current_connection:[29,3,1,""],dialect:[29,3,1,""],first:[29,3,1,""],iterate:[29,3,1,""],one:[29,3,1,""],one_or_none:[29,3,1,""],raw_pool:[29,3,1,""],repr:[29,3,1,""],scalar:[29,3,1,""],status:[29,3,1,""],transaction:[29,3,1,""],update_execution_options:[29,3,1,""]},"gino.exceptions":{GinoException:[30,5,1,""],InitializedError:[30,5,1,""],MultipleResultsFound:[30,5,1,""],NoResultFound:[30,5,1,""],NoSuchRowError:[30,5,1,""],UninitializedError:[30,5,1,""],UnknownJSONPropertyError:[30,5,1,""]},"gino.json_support":{ArrayProperty:[32,2,1,""],BooleanProperty:[32,2,1,""],DateTimeProperty:[32,2,1,""],IntegerProperty:[32,2,1,""],JSONProperty:[32,2,1,""],ObjectProperty:[32,2,1,""],StringProperty:[32,2,1,""]},"gino.json_support.ArrayProperty":{decode:[32,3,1,""],encode:[32,3,1,""]},"gino.json_support.BooleanProperty":{decode:[32,3,1,""],encode:[32,3,1,""],make_expression:[32,3,1,""]},"gino.json_support.DateTimeProperty":{decode:[32,3,1,""],encode:[32,3,1,""],make_expression:[32,3,1,""]},"gino.json_support.IntegerProperty":{decode:[32,3,1,""],encode:[32,3,1,""],make_expression:[32,3,1,""]},"gino.json_support.JSONProperty":{decode:[32,3,1,""],encode:[32,3,1,""],get_profile:[32,3,1,""],make_expression:[32,3,1,""],reload:[32,3,1,""],save:[32,3,1,""]},"gino.json_support.ObjectProperty":{decode:[32,3,1,""],encode:[32,3,1,""]},"gino.json_support.StringProperty":{make_expression:[32,3,1,""]},"gino.loader":{AliasLoader:[33,2,1,""],CallableLoader:[33,2,1,""],ColumnLoader:[33,2,1,""],Loader:[33,2,1,""],ModelLoader:[33,2,1,""],TupleLoader:[33,2,1,""],ValueLoader:[33,2,1,""]},"gino.loader.CallableLoader":{do_load:[33,3,1,""]},"gino.loader.ColumnLoader":{do_load:[33,3,1,""]},"gino.loader.Loader":{do_load:[33,3,1,""],get:[33,3,1,""],get_columns:[33,3,1,""],get_from:[33,3,1,""],query:[33,3,1,""]},"gino.loader.ModelLoader":{distinct:[33,3,1,""],do_load:[33,3,1,""],get_columns:[33,3,1,""],get_from:[33,3,1,""],load:[33,3,1,""],none_as_none:[33,3,1,""],on:[33,3,1,""]},"gino.loader.TupleLoader":{do_load:[33,3,1,""]},"gino.loader.ValueLoader":{do_load:[33,3,1,""]},"gino.schema":{AsyncSchemaDropper:[34,2,1,""],AsyncSchemaGenerator:[34,2,1,""],AsyncSchemaTypeMixin:[34,2,1,""],AsyncVisitor:[34,2,1,""],GinoSchemaVisitor:[34,2,1,""],patch_schema:[34,1,1,""]},"gino.schema.AsyncSchemaDropper":{visit_foreign_key_constraint:[34,3,1,""],visit_index:[34,3,1,""],visit_metadata:[34,3,1,""],visit_sequence:[34,3,1,""],visit_table:[34,3,1,""]},"gino.schema.AsyncSchemaGenerator":{visit_foreign_key_constraint:[34,3,1,""],visit_index:[34,3,1,""],visit_metadata:[34,3,1,""],visit_sequence:[34,3,1,""],visit_table:[34,3,1,""]},"gino.schema.AsyncSchemaTypeMixin":{create_async:[34,3,1,""],drop_async:[34,3,1,""]},"gino.schema.AsyncVisitor":{traverse_single:[34,3,1,""]},"gino.schema.GinoSchemaVisitor":{create:[34,3,1,""],create_all:[34,3,1,""],drop:[34,3,1,""],drop_all:[34,3,1,""]},"gino.strategies":{GinoStrategy:[35,2,1,""]},"gino.strategies.GinoStrategy":{create:[35,3,1,""],engine_cls:[35,4,1,""],name:[35,4,1,""]},"gino.transaction":{GinoTransaction:[36,2,1,""]},"gino.transaction.GinoTransaction":{commit:[36,3,1,""],connection:[36,3,1,""],raise_commit:[36,3,1,""],raise_rollback:[36,3,1,""],raw_transaction:[36,3,1,""],rollback:[36,3,1,""]},gino:{aiocontextvars:[20,0,0,"-"],api:[21,0,0,"-"],bakery:[22,0,0,"-"],create_engine:[19,1,1,""],crud:[23,0,0,"-"],declarative:[24,0,0,"-"],dialects:[25,0,0,"-"],engine:[29,0,0,"-"],exceptions:[30,0,0,"-"],ext:[31,0,0,"-"],get_version:[19,1,1,""],json_support:[32,0,0,"-"],loader:[33,0,0,"-"],schema:[34,0,0,"-"],strategies:[35,0,0,"-"],transaction:[36,0,0,"-"]}},objnames:{"0":["py","module","Python module"],"1":["py","function","Python function"],"2":["py","class","Python class"],"3":["py","method","Python method"],"4":["py","attribute","Python attribute"],"5":["py","exception","Python exception"]},objtypes:{"0":"py:module","1":"py:function","2":"py:class","3":"py:method","4":"py:attribute","5":"py:exception"},terms:{"0020":43,"0x10a8ba860":14,"100":[3,4,23,44],"101":[0,4],"106":41,"109":41,"112":41,"113":[10,41],"114":41,"11th":4,"123":7,"126":41,"127":44,"128":36,"141":41,"142":41,"146":41,"147":41,"159":41,"160":41,"174":41,"178":41,"180":41,"183":41,"184":41,"187":41,"191":41,"192":41,"193":41,"198":41,"1990":11,"2017":[17,43],"2018":[12,17],"2019":17,"202":41,"2020":[16,17],"204":41,"213":41,"215":41,"216":41,"21s":44,"224":41,"225":41,"228":41,"231":41,"249":3,"258":41,"261":41,"265":41,"275":41,"279":41,"280":41,"281":41,"282":41,"287":41,"288":41,"289":41,"291":41,"297":41,"298":41,"302":41,"304":41,"305":41,"307":41,"308":41,"309":41,"310":41,"313":41,"323":41,"32c0feba61ea":44,"32c0feba61ea_add_users_t":44,"333":41,"334":41,"335":41,"351":41,"365":41,"378":41,"382":41,"387":41,"393":41,"395":41,"396":41,"3apull_request":8,"400":38,"401":41,"402":41,"403":41,"404":44,"406":41,"407":41,"408":41,"411":41,"425":41,"427":41,"431847":12,"433":41,"437":41,"440":41,"441":41,"447":41,"451":41,"457":41,"478":41,"486":41,"487":41,"4888":43,"4c59ad":41,"504":41,"518":41,"520":41,"53010":44,"53015":44,"533":41,"538":41,"5432":[8,38,39,44],"5433":8,"567":41,"569":41,"573":41,"577":41,"579":41,"582":41,"585":41,"592":41,"599":41,"600":[8,41],"609":41,"627":43,"628":41,"629":41,"63562":44,"63563":44,"637":41,"638":41,"655":41,"659":41,"660":41,"661":41,"662":41,"667":41,"672":41,"673":41,"674":41,"693":41,"694":41,"695":41,"696":41,"8000":44,"\u00e1d\u00e1m":[10,41],"\u4e00\u4e2a\u6c47\u7387":43,"\u4e00\u5b9a\u8981\u5168":43,"\u4e00\u65e6\u4ee3\u7801\u521d\u5177\u89c4\u6a21":43,"\u4e00\u679a":43,"\u4e00\u6837":43,"\u4e00\u79d2\u53ef\u8bfb\u767e\u4e07\u884c\u7684":43,"\u4e00\u7ad9\u5f0f\u5730\u89e3\u51b3\u4e86\u5e38\u7528":43,"\u4e09\u5e74\u540e\u7684\u4eca\u5929":43,"\u4e0a\u4e0b\u6587\u7ba1\u7406":43,"\u4e0a\u624b\u540e\u4f9d\u7136\u53ef\u4ee5\u5feb\u901f":43,"\u4e0a\u7ed9":43,"\u4e0a\u9762\u90a3\u4e2a":43,"\u4e0d\u4f1a\u53bb\u65e0\u7aef\u731c\u6d4b\u4e3b\u4eba\u7684\u610f\u56fe":43,"\u4e0d\u540c\u7684\u662f":43,"\u4e0d\u65ad\u6f14\u8fdb\u6210\u719f":43,"\u4e0d\u662f":43,"\u4e0d\u662f\u4e00\u4e2a\u4f20\u7edf\u7684":43,"\u4e0d\u6b62\u8fd9\u6837":43,"\u4e0e":43,"\u4e13\u4e1a\u7248\u5168\u5bb6\u6876":43,"\u4e13\u4e1a\u9886\u57df\u7684":43,"\u4e1a\u4f59\u65f6\u95f4\u9664\u4e86\u5f00\u53d1\u7ef4\u62a4":43,"\u4e2d\u8d1f\u8d23\u6784\u5efa":43,"\u4e3a":43,"\u4e3a\u4e86\u8ba9\u4e0d\u540c\u5e94\u7528\u573a\u666f\u4e0b\u7684\u7528\u6237\u4f53\u9a8c\u5230\u6700\u5927\u7684\u5584\u610f":43,"\u4e3a\u4e86\u9e21\u6bdb\u849c\u76ae\u7684\u5c0f\u4e8b\u5927\u52a8\u5e72\u6208":43,"\u4e3a\u4ec0\u4e48\u8fd9\u4e48\u773c\u719f":43,"\u4e3b\u8981\u8bf4\u7684\u662f\u5f00\u53d1\u6548\u7387":43,"\u4e4b\u7985\u5b8c\u7f8e\u8868\u8fbe\u4e86":43,"\u4e5f\u53ef\u4ee5\u7528":43,"\u4e5f\u63d0\u4f9b\u4e86\u5bf9\u8c61\u6620\u5c04\u7684\u5de5\u5177":43,"\u4e5f\u662f":43,"\u4e5f\u66fe\u5728\u521b\u4e1a\u7684\u6f6e\u6d41\u4e2d\u7559\u4e0b\u8eab\u5f71":43,"\u4e5f\u6709\u4e00\u5957\u7cbe\u5999\u7684\u663e\u5f0f\u673a\u5236":43,"\u4e86\u89e3\u4e00\u4e0b":43,"\u4e8c\u5341\u4e94\u516d\u5e74\u7684\u7f16\u7a0b\u53f2\u548c\u5341\u4e09\u56db\u5e74\u7684\u5de5\u4f5c\u7ecf\u9a8c\u6559\u4f1a\u4e86\u6211\u8bb8\u591a\u8f6f\u4ef6\u5f00\u53d1\u7684\u5965\u4e49":43,"\u4e92\u91d1":43,"\u4eb2\u8eab\u7ecf\u5386\u5e76\u89c1\u8bc1\u4e86\u8f6f\u4ef6\u6280\u672f\u968f\u7740\u624b\u6e38":43,"\u4ec0\u4e48\u7684\u90fd\u6709":43,"\u4ece\u4e0a\u624b\u6559\u7a0b\u5230\u539f\u7406\u8bf4\u660e\u5e94\u6709\u5c3d\u6709":43,"\u4ece\u6bd4\u8f83\u65e9\u5c31\u89e3\u8026\u4e86\u4e0d\u540c":43,"\u4ece\u7b80\u5355\u793a\u8303\u5230\u751f\u4ea7\u73af\u5883\u7684\u5404\u79cd\u4f8b\u5b50\u54c1\u79cd\u9f50\u5168":43,"\u4ee5\u4e0b\u662f\u8fd1\u6765\u7edf\u8ba1\u5230\u7684\u5173\u4e8e":43,"\u4ee5\u53ca":43,"\u4ee5\u53ca\u4e0b\u9762\u8fd9\u4e9b\u4e00\u76f4\u9700\u8981\u7684\u5e2e\u52a9":43,"\u4ee5\u53ca\u4e2d\u6587":43,"\u4ee5\u540c\u65f6\u83b7\u53d6\u6240\u6709\u7684\u4e66\u548c\u4ed6\u4eec\u7684\u4f5c\u8005":43,"\u4ee5\u8282\u7701\u5b66\u4e60\u548c\u8fc1\u79fb\u6210\u672c":43,"\u4f18\u52bf\u4e0e\u4e0d\u8db3":42,"\u4f20\u7edf":43,"\u4f46":43,"\u4f46\u4e0d\u662f\u4e00\u4e2a\u4f20\u7edf\u7684":43,"\u4f46\u5e94\u7528\u5230\u5927\u578b\u9879\u76ee\u4e2d\u5374\u5341\u5206\u8003\u9a8c\u5f00\u53d1\u4eba\u5458\u7684\u5e73\u5747\u6c34\u5e73":43,"\u4f46\u662f\u5bf9\u4e8e\u66f4\u590d\u6742\u7684\u67e5\u8be2":43,"\u4f46\u6ca1\u5f81\u5f97\u540c\u610f\u5c31\u4e0d\u8d34\u51fa\u6765\u4e86":43,"\u4f46\u90fd\u662f\u540c\u884c\u5c31\u4e0d\u591a\u8bc4\u4ef7\u4e86":43,"\u4f60\u4e00\u5b9a\u4f1a\u6709\u611f\u77e5\u7684":43,"\u4f60\u53ef\u4ee5\u7528":43,"\u4f60\u751a\u81f3\u53ef\u4ee5\u624b\u5199\u4efb\u4f55":43,"\u4f60\u80af\u5b9a\u8981\u95ee\u4e00\u53e5":43,"\u4f8b\u5982\u524d\u9762\u7684":43,"\u4fc4\u6587\u7684\u7ffb\u8bd1":43,"\u4fc4\u8bed\u6559\u7a0b":43,"\u4fee":43,"\u501f\u9274\u4e86":43,"\u505a\u529f\u80fd":43,"\u5143":43,"\u5148\u8bf4":42,"\u5168\u90fd\u517c\u5bb9":43,"\u5173\u4e8e\u4f5c\u8005":42,"\u5176\u4e2d":43,"\u518d\u52a0\u4e0a":43,"\u518d\u8bf4":42,"\u5199":43,"\u51fa\u54c1\u5fc5\u5c5e\u7cbe\u54c1\u7684":43,"\u51fa\u54c1\u65b9\u662f":43,"\u51fa\u95ee\u9898\u627e\u4e0d\u5230\u539f\u56e0":43,"\u5219\u4f1a\u5c06\u8fd9\u4e9b\u53d8\u66f4\u5e94\u7528\u5230\u6570\u636e\u5e93\u91cc":43,"\u5219\u662f":43,"\u521b\u9020\u51fa\u4e86\u4e00\u79cd\u7206\u70b8\u5f0f\u7684\u5316\u5b66\u53cd\u5e94":43,"\u52a0\u4e00\u9897\u661f\u661f":43,"\u52a0\u8f7d\u5668\u4e0e\u5173\u7cfb":43,"\u52a0\u8f7d\u5668\u7684\u7528\u6cd5\u4e5f\u662f\u5f88\u7b80\u5355\u7684":43,"\u5341\u5206\u5feb\u6377":43,"\u5343\u661f\u9879\u76ee":43,"\u5373\u5173\u7cfb\u5bf9\u8c61\u6620\u5c04":43,"\u5373\u88c5\u5373\u7528":43,"\u539f\u6559\u65e8\u4e3b\u4e49\u8005":43,"\u53bb":43,"\u53c2\u4e0e\u8ba8\u8bba":43,"\u53c2\u8003\u6587\u732e":42,"\u53c8\u7b80\u5355\u660e\u4e86\u5730\u8bbf\u95ee\u6570\u636e\u5e93\u5462":43,"\u53cd\u566c\u7684\u60c5\u666f":43,"\u53e6\u4e00\u65b9\u9762":43,"\u53e6\u5916":43,"\u53ea\u613f\u5b9a\u4e49":43,"\u53ea\u6709\u5f02\u6b65\u6267\u884c\u65f6\u624d\u7528\u5230":43,"\u53ef\u4ee5\u76f4\u63a5\u83b7\u53d6\u5230":43,"\u53ef\u4ee5\u8c28\u614e\u5730\u7528\u4e8e\u751f\u4ea7\u73af\u5883\u4e86":43,"\u53ef\u5b9a\u5236\u5316\u7684\u52a0\u8f7d\u5668":43,"\u53ef\u9009":43,"\u5404\u4e2a":43,"\u5404\u5927\u6d41\u884c\u5f02\u6b65":43,"\u5404\u79cd":43,"\u540c\u65f6":43,"\u540c\u65f6\u4e5f\u4e0d\u9700\u8981\u4e3a\u8fd9\u79cd\u660e\u786e\u6027\u4ed8\u51fa\u8fc7\u5927\u7684\u5de5\u7a0b\u4ee3\u4ef7":43,"\u5462":43,"\u548c":43,"\u54a6":43,"\u54e6\u4e0d":43,"\u56de\u7b54\u95ee\u9898":43,"\u56e0\u4e3a\u7269\u6781\u5fc5\u53cd":43,"\u56e0\u6b64":43,"\u56e0\u6b64\u8fd8\u4e0d\u80fd\u5b8c\u5168\u53d1\u6325":43,"\u5728\u5e26\u6765\u751f\u6d3b\u4fbf\u5229\u7684\u540c\u65f6":43,"\u5728\u6267\u884c\u6548\u7387\u4e0a\u4e5f\u6ca1\u843d\u4e0b":43,"\u5728\u7ebf\u6e38\u620f\u7b49\u9ad8\u5e76\u53d1\u9886\u57df":43,"\u5728\u8fd9\u4e2a\u70e7\u8111\u7684\u5f02\u6b65\u4e16\u754c\u91cc":43,"\u5728\u8fd9\u91cc\u5c31\u4e0d\u4e00\u4e00\u5217\u4e3e\u4e86":43,"\u57fa\u4e8e":43,"\u57fa\u7840\u6559\u7a0b":43,"\u586b\u8865\u4e86\u56fd\u5185\u5916":43,"\u589e\u5220\u6539\u67e5":43,"\u5927":43,"\u5927\u5b66\u91cc\u5f00\u59cb\u5199":43,"\u5927\u91cf\u7684\u6210\u529f\u6848\u4f8b\u4e5f\u8bc1\u660e\u4e86":43,"\u5929\u751f\u538c\u6076":43,"\u5982\u679c\u50cf\u8fd9\u6837":43,"\u5988\u5988\u518d\u4e5f\u4e0d\u7528\u62c5\u5fc3\u6211\u4e0d\u4f1a\u96c6\u6210":43,"\u5b83\u4eec":43,"\u5b83\u4eec\u5173\u6ce8\u7684\u91cd\u70b9\u4e0e":43,"\u5b83\u7684\u5168\u79f0\u662f":43,"\u5b83\u7684\u5b9e\u4f8b":43,"\u5b98\u5ba3":42,"\u5b9a\u4e0b\u4e86\u4e24\u4e2a\u4e1a\u7ee9\u76ee\u6807":43,"\u5b9e\u4f8b":43,"\u5b9e\u4f8b\u7684":43,"\u5b9e\u4f8b\u8bbe\u7f6e\u5230":43,"\u5bf9":43,"\u5bf9\u4e8e\u4e0a\u4e86\u89c4\u6a21\u7684\u5f02\u6b65\u5de5\u7a0b\u9879\u76ee\u6765\u8bf4\u5c24\u4e3a\u91cd\u8981":43,"\u5bf9\u4e8e\u5982\u4f55\u5c06\u6570\u636e\u5e93\u67e5\u8be2\u7ed3\u679c\u7ec4\u88c5\u6210\u5185\u5b58\u5bf9\u8c61\u53ca\u5176\u5c5e\u6027":43,"\u5bf9\u4e8e\u7b80\u5355\u76f4\u89c2\u7684\u4e00\u5bf9\u4e00\u52a0\u8f7d":43,"\u5bf9\u5176\u6267\u884c":43,"\u5bf9\u8c61":43,"\u5bf9\u8c61\u5173\u7cfb\u6620\u5c04":43,"\u5c06\u6570\u636e\u5e93\u8fd4\u56de\u7ed3\u679c\u7684\u6bcf\u4e00\u884c\u4e2d":43,"\u5c0f\u65f6\u5019\u5199":43,"\u5c31\u53d8\u6210\u4e86\u4eba\u540d":43,"\u5c31\u5b9e\u73b0\u4e86":43,"\u5c31\u662f\u4ed6\u4eec\u7684\u4f5c\u54c1":43,"\u5c31\u662f\u5185\u5b58\u91cc\u9762\u7684\u5e38\u89c4\u5bf9\u8c61":43,"\u5c31\u662f\u660e\u786e\u6027\u7684\u5173\u952e":43,"\u5c31\u662f\u6709\u4eba\u53d7\u4e0d\u4e86\u4e86\u81ea\u5df1\u5199\u4e86\u4e00\u4e2a\u7c7b\u578b\u6ce8\u89e3":43,"\u5c31\u6ca1\u6709\u6570\u636e\u5e93\u64cd\u4f5c":43,"\u5c5e\u4e8e":43,"\u5c5e\u6027\u4e0a":43,"\u5c81\u5f00\u59cb\u63a5\u89e6\u7f16\u7a0b":43,"\u5de5\u4f5c\u5934\u4e94\u5e74\u8f6c\u5411\u4e86":43,"\u5df2\u7ecf\u521d\u6b65\u5177\u5907\u53d1\u5e03":43,"\u5e74\u521b\u4f5c\u4e4b\u521d":43,"\u5e74\u751f\u4eba":43,"\u5e76\u4e0d\u662f\u4ece\u5934\u9020\u8f6e\u5b50":43,"\u5e76\u63a5\u89e6\u5230\u4e86":43,"\u5efa\u8bbe\u793e\u4f1a\u4e3b\u4e49":42,"\u5f00\u53d1\u4eba\u5458\u7684\u65f6\u95f4\u786e\u5b9e\u6bd4\u673a\u5668\u7684\u65f6\u95f4\u503c\u94b1":43,"\u5f00\u53d1\u5e94\u7528\u7a0b\u5e8f\u7684\u65f6\u5019\u4e0d\u7528\u62c5\u5fc3\u4f1a\u88ab\u610f\u6599\u4e4b\u5916\u7684\u884c\u4e3a\u6240\u60ca\u5413\u5230":43,"\u5f00\u6e90\u793e\u533a\u91cc\u4e5f\u76f8\u7ee7\u51fa\u73b0\u4e86\u50cf":43,"\u5f00\u7bb1\u5373\u7528\u7684\u6570\u636e\u5e93\u53d8\u66f4\u7ba1\u7406\u5de5\u5177":43,"\u5f02\u6b65":43,"\u5f02\u6b65\u7f16\u7a0b\u518d\u6dfb\u4e00\u5229\u5668":42,"\u5f02\u6b65\u7f16\u7a0b\u8fd9\u4e2a\u8bdd\u9898\u4e5f\u5728\u9010\u6e10\u5347\u6e29":43,"\u5f15\u64ce":43,"\u5f15\u64ce\u4e0e\u8fde\u63a5":43,"\u5f62\u4f3c\u800c\u795e\u4e0d\u4f3c":43,"\u5f80\u5f80\u4f1a\u9009\u62e9\u727a\u7272\u660e\u786e\u6027":43,"\u5f88\u7b80\u5355\u7684\u4e00\u4e2a\u5916\u8fde\u63a5\u67e5\u8be2":43,"\u5f97\u5929\u72ec\u539a\u7684\u7075\u6d3b\u6027":43,"\u5feb\u4e50\u5730\u7f16\u7a0b":43,"\u5feb\u6377\u65b9\u5f0f":43,"\u6027\u80fd\u83ab\u540d\u5176\u5999\u7684\u5dee":43,"\u610f\u5473\u7740\u6211\u4eec\u8981\u8df3\u51fa\u53bb\u6267\u884c\u6570\u636e\u5e93\u64cd\u4f5c\u4e86":43,"\u6210\u529f\u5b9e\u73b0\u4e86\u5bf9\u540c\u671f\u7ade\u54c1":43,"\u6211\u5c31\u7ed9":43,"\u6211\u771f":43,"\u6211\u7d22\u6027\u5728":43,"\u6216\u8005\u7528":43,"\u6240\u4ee5":43,"\u6240\u4ee5\u5728":43,"\u6240\u4ee5\u6b22\u8fce\u5927\u5bb6\u4e00\u8d77\u6765\u5efa\u8bbe":43,"\u6240\u4ee5\u8fd9\u4e9b\u529f\u80fd\u4f1a\u9646\u7eed\u5728":43,"\u6240\u6709\u4eba":43,"\u6240\u6709\u8fd9\u4e9b\u95ee\u9898\u5982\u679c\u518d\u653e\u8fdb\u5f02\u6b65\u7f16\u7a0b\u7684\u73af\u5883\u91cc":43,"\u624b\u6cd5":43,"\u6267\u884c":43,"\u627e":43,"\u6307\u54ea\u513f\u6253\u54ea\u513f":43,"\u6362\u53e5\u8bdd\u8bf4":43,"\u63d0":43,"\u63d0\u5347\u4e86\u5199\u4ee3\u7801\u7684\u5e78\u798f\u6307\u6570":43,"\u63d0\u5efa\u8bae":43,"\u6570\u636e\u5e93\u4e8b\u52a1":43,"\u6570\u636e\u5e93\u4e8b\u52a1\u5c01\u88c5\u548c\u5d4c\u5957":43,"\u6587\u5a31":43,"\u65b0\u5a92\u4f53":43,"\u65b9\u4fbf\u5feb\u6377":42,"\u65b9\u8a00\u548c\u9a71\u52a8\u7684\u96c6\u6210":43,"\u65e0\u989d\u5916\u4f9d\u8d56\u5173\u7cfb":43,"\u65e2\u7b80\u5355\u53c8\u660e\u4e86\u6709\u6ca1\u6709":43,"\u660e\u786e\u6027":43,"\u662f":43,"\u662f\u4e00\u4e2a":43,"\u662f\u4e00\u4e2a\u5f00\u6e90\u9879\u76ee":43,"\u662f\u4e00\u7c7b\u5f00\u53d1\u4eba\u5458\u559c\u95fb\u4e50\u89c1\u7684\u6548\u7387\u5de5\u5177":43,"\u662f\u4e0d\u662f\u5341\u5206\u65b9\u4fbf":43,"\u662f\u5b8c\u5168\u65e0\u72b6\u6001\u7684\u666e\u901a":43,"\u662f\u7528\u6765\u8bbf\u95ee\u6570\u636e\u5e93\u7684":43,"\u662f\u7684":43,"\u662f\u8c01":42,"\u66f4\u591a\u7684\u4f8b\u5b50\u548c\u6587\u6863":43,"\u66f4\u91cd\u8981\u7684\u662f\u5e26\u6765\u4e86\u6574\u4e2a":43,"\u6700\u540e":43,"\u6700\u540e\u4e5f\u662f\u6700\u91cd\u8981\u7684":43,"\u6700\u540e\u5c06":43,"\u6700\u5927\u7a0b\u5ea6\u7684\u4fbf\u5229":43,"\u6700\u5c11\u4fb5\u5165\u578b":43,"\u6709\u6ca1\u6709\u529e\u6cd5\u53ef\u4ee5\u65e2\u65b9\u4fbf\u5feb\u6377":43,"\u670d\u52a1":43,"\u671f\u95f4\u8d21\u732e\u4e86":43,"\u6765\u4fee\u6539\u5c5e\u6027":43,"\u6765\u521b\u5efa\u65b0\u7684\u5b9e\u4f8b":43,"\u6765\u6362\u53d6\u4fbf\u6377\u6027":43,"\u6781\u5927\u5730":43,"\u67d0\u4e9b\u573a\u666f\u4e0b":43,"\u6846\u67b6":43,"\u6846\u67b6\u4e86":43,"\u6846\u67b6\u63d2\u4ef6\u7684\u7ef4\u62a4\u5de5\u4f5c\u9700\u8981\u591a\u4eba\u8ba4\u9886":43,"\u6846\u67b6\u6765\u8bf4\u662f\u4e0d\u53ef\u63a5\u53d7\u7684":43,"\u6846\u67b6\u7684\u5b9a\u5236\u7248\u63d2\u4ef6":43,"\u6b22\u8fce\u6765\u5230":43,"\u6b63\u72b9\u5982":43,"\u6bd4\u5982\u4e00\u4e2a\u7528\u6237\u53ef\u80fd\u5199\u4e86\u5f88\u591a\u672c\u4e66":43,"\u6bd4\u5982\u6267\u884c":43,"\u6bd4\u5982\u6ca1\u6709\u7167\u987e\u5230":43,"\u6bd4\u5982\u7528":43,"\u6bd4\u5982\u8bf4":43,"\u6c7d\u8f66\u7b49\u884c\u4e1a\u7684\u8d77\u8d77\u4f0f\u4f0f":43,"\u6ca1\u6709":43,"\u6ca1\u6709\u53d1\u7968":43,"\u6ca1\u6709\u9519":43,"\u6df1\u53d7\u4fc4\u7f57\u65af\u548c\u4e4c\u514b\u5170\u4eba\u6c11\u7684\u7231\u6234":43,"\u706b\u529b\u5168\u5f00\u578b":43,"\u7136\u540e\u5b9a\u5236\u52a0\u8f7d\u5668\u81ea\u52a8\u52a0\u8f7d\u6210\u671f\u671b\u7684\u5bf9\u8c61\u5173\u7cfb":43,"\u7136\u540e\u5c06\u8be5\u884c\u4e2d\u5269\u4e0b\u7684\u5c5e\u4e8e":43,"\u7136\u540e\u8fd9\u6837\u6765\u52a0\u8f7d\u8fd9\u79cd\u591a\u5bf9\u4e00\u5173\u7cfb":43,"\u7248\u672c\u4e2d\u8ddf\u4e0a":43,"\u7279\u522b\u611f\u8c22":43,"\u751f\u957f\u7684\u6e29\u5e8a":43,"\u7528":43,"\u7528\u6237\u5305":43,"\u7535\u5546":43,"\u7684":43,"\u7684\u540c\u5b66\u6765\u8bf4\u53ef\u80fd\u5e76\u4e0d\u964c\u751f":43,"\u7684\u57fa\u7840\u4e0a\u5f00\u53d1\u7684":43,"\u7684\u589e\u5f3a\u63d2\u4ef6":43,"\u7684\u590d\u6742\u5ea6\u4e86":43,"\u7684\u5b57\u6bb5\u52a0\u8f7d\u6210\u4e00\u4e2a":43,"\u7684\u5b66\u4e60\u66f2\u7ebf\u524d\u5e73\u540e\u9661":43,"\u7684\u5b9a\u4e49\u98ce\u683c":43,"\u7684\u5e94\u7528\u6848\u4f8b":43,"\u7684\u5e95\u5c42\u6838\u5fc3":43,"\u7684\u5f3a\u529b\u52a0\u6301":43,"\u7684\u5f88\u591a\u8bbe\u8ba1\u90fd\u53d7\u5230\u4e86\u660e\u786e\u6027\u7684\u5f71\u54cd":43,"\u7684\u652f\u6301":43,"\u7684\u6587\u6863":43,"\u7684\u6700\u5927\u4f18\u52bf\u8fd8\u662f\u5728\u4e8e\u5145\u5206\u5e73\u8861\u4e86\u5f00\u53d1\u6548\u7387\u548c\u660e\u786e\u6027\u4e4b\u95f4\u7684\u8fa9\u8bc1\u77db\u76fe\u5173\u7cfb":43,"\u7684\u6f5c\u80fd":43,"\u7684\u751f\u6001\u73af\u5883":43,"\u7684\u7528\u6237\u5bf9\u8c61":43,"\u7684\u7acb\u573a":43,"\u7684\u7c7b\u578b\u63d0\u793a":43,"\u7684\u8d21\u732e":43,"\u7684\u9012\u5f52\u5b9a\u4e49":43,"\u7684\u964d\u7ef4\u6253\u51fb":43,"\u76ee\u524d\u4e5f\u662f\u4e0d\u652f\u6301\u7684":43,"\u76ee\u524d\u5728\u829d\u5927\u7ee7\u7eed\u505a\u751f\u7269\u5927\u6570\u636e\u76f8\u5173\u7684\u5f00\u6e90\u9879\u76ee":43,"\u76ee\u524d\u6025\u9700\u5e2e\u52a9\u7684\u6709":43,"\u76ee\u524d\u652f\u6301\u4e09\u79cd\u4e0d\u540c\u7a0b\u5ea6\u7684\u7528\u6cd5":43,"\u76ee\u524d\u7684\u4e0d\u8db3\u4e4b\u5904\u8fd8\u6709\u4e00\u4e9b":43,"\u77ff\u5708":43,"\u793e\u4ea4":43,"\u7a0d\u6709\u4e0d\u540c":43,"\u7a33\u5b9a\u7248\u53d1\u5e03\u7684\u524d\u5915\u505a\u4e2a\u5e74\u7ec8\u603b\u7ed3":43,"\u7a33\u5b9a\u7248\u7684\u5404\u79cd\u6761\u4ef6":43,"\u7a7a\u624b\u63a5":43,"\u7b14\u8005\u5de5\u4f5c\u4e0a\u5f00\u53d1\u7684\u4e00\u4e2a\u670d\u52a1":43,"\u7b49":43,"\u7b49\u4f18\u79c0\u7684\u5f02\u6b65":43,"\u7b49\u5230\u9700\u8981\u64cd\u4f5c\u6570\u636e\u5e93\u7684\u65f6\u5019":43,"\u7b49\u591a\u9879\u4fbf\u6377\u529f\u80fd":43,"\u7b49\u5f00\u6e90\u9879\u76ee\u4e14\u4e00\u53d1\u4e0d\u53ef\u6536\u62fe":43,"\u7b49\u6846\u67b6\u7684\u9646\u7eed\u6d8c\u73b0":43,"\u7b49\u9879\u76ee\u4e86\u89e3\u4e86\u5f02\u6b65\u7f16\u7a0b":43,"\u7b80\u5355\u660e\u4e86":42,"\u7c7b":43,"\u7c7b\u4f3c":43,"\u7cbe\u51c6\u63a7\u5236\u52a0\u8f7d\u884c\u4e3a":43,"\u7ec8\u8eab\u4e0d\u5a5a\u578b":43,"\u7edd\u4e0d\u662f\u9ed1\u54c8":43,"\u7edd\u5bf9\u7eff\u8272\u73af\u4fdd\u65e0\u6bd2\u526f\u4f5c\u7528":43,"\u7ef4\u57fa\u767e\u79d1":43,"\u7ef4\u62a4\u793e\u533a":43,"\u800c":43,"\u800c\u5168\u6743\u4ea4\u7ed9\u7528\u6237\u6765\u660e\u786e\u5730\u5b9a\u4e49":43,"\u800c\u662f\u5728":43,"\u804a\u5929\u673a\u5668\u4eba":43,"\u80fd\u53eb\u4e0a\u540d\u5b57\u7684\u50cf":43,"\u80fd\u5728\u5feb\u901f\u539f\u578b\u5f00\u53d1\u4e2d\u5927\u5c55\u8eab\u624b":43,"\u81ea\u7136\u662f\u4f3a\u5019\u5230\u5bb6\u7684":43,"\u867d\u7136\u6587\u6863\u8fd8\u5728\u52aa\u529b\u7f16\u5199\u4e2d":43,"\u867d\u7136\u662f":43,"\u8868":43,"\u8868\u7ed3\u6784\u5b9a\u4e49":43,"\u88ab\u5e7f\u6cdb\u5e94\u7528\u4e8e\u8bf8\u5982\u5b9e\u65f6\u6c47\u7387":43,"\u8981\u7528":43,"\u8bbf\u95ee\u5c5e\u6027":43,"\u8dd1\u8d77\u6765\u4e5f\u662f\u53ef\u4ee5\u98de\u5feb\u7684":43,"\u8f7b\u91cf\u7ea7":43,"\u8fc1\u79fb":43,"\u8fd8\u4f1a\u5076\u5c14\u4fee\u4e00\u4fee":43,"\u8fd8\u4f1a\u8fd4\u56de\u4e00\u4e2a\u5305\u542b\u672c\u6b21\u53d8\u66f4\u7684\u4e2d\u95f4\u7ed3\u679c":43,"\u8fd8\u63d0\u4f9b\u4e86":43,"\u8fd8\u662f\u7b14\u8005\u81ea\u5df1\u5199\u7684\u4e00\u4e2a\u5de5\u5177":43,"\u8fd8\u6709\u51e0\u4e2a\u5546\u7528\u7684":43,"\u8fd8\u6709\u5f88\u591a\u7c7b\u4f3c\u7684\u7279\u6027":43,"\u8fd8\u8d34\u5fc3\u5730\u63d0\u4f9b\u4e86\u4e2d\u6587\u6587\u6863":43,"\u8fd9\u4e2a\u9879\u76ee\u5c31\u53eb":43,"\u8fd9\u4e48\u505a\u9664\u4e86\u80fd\u4fdd\u6301\u719f\u6089\u7684\u5473\u9053":43,"\u8fd9\u4e48\u5b9a\u4e49\u8868\u7ed3\u6784\u751a\u81f3\u8ba9\u4eba\u6709\u70b9\u5c0f\u5174\u594b":43,"\u8fd9\u4e9b\u64cd\u4f5c\u90fd\u4e0d\u4f1a\u8bbf\u95ee\u6570\u636e\u5e93":43,"\u8fd9\u4ee3\u7801\u4f60\u8ba9\u6211\u600e\u4e48\u8c03\u8bd5":43,"\u8fd9\u5bf9\u4e8e\u4e00\u6b3e\u4f18\u79c0\u7684\u5f02\u6b65":43,"\u8fd9\u5c31\u662f":43,"\u8fd9\u662f\u8c01":43,"\u8fd9\u91cc\u7684":43,"\u8fde\u63a5\u6c60\u7ba1\u7406\u548c\u61d2\u52a0\u8f7d":43,"\u901a\u8fc7":43,"\u90a3\u4e3a\u4ec0\u4e48\u975e\u8bf4":43,"\u90a3\u5c31\u662f":43,"\u90e8":43,"\u90fd\u662f\u53ea\u5728\u5185\u5b58\u91cc\u4fee\u6539\u5bf9\u8c61\u7684\u5c5e\u6027":43,"\u90fd\u6709\u53ef\u80fd\u89e6\u53d1\u4e00\u5927\u5806\u610f\u60f3\u4e0d\u5230\u7684\u6570\u636e\u5e93\u8c03\u7528":43,"\u914d\u5408\u4e00\u4e2a\u76f4\u89c2\u7684\u52a0\u8f7d\u5668":43,"\u91cc\u7684\u5bf9\u8c61\u6620\u5c04\u4e0d\u80fd\u4e22":43,"\u91cd\u89c6\u5f00\u53d1\u6548\u7387\u7684\u6982\u5ff5\u5bf9\u4e8e\u5199":43,"\u957f\u671f\u6d3b\u8dc3\u7684\u8d21\u732e\u8005\u8fd8\u80fd\u83b7\u8d60\u4ef7\u503c":43,"\u968f\u4fbf\u4e00\u53e5":43,"\u968f\u7740":43,"\u968f\u7740\u8fd9\u51e0\u5e74":43,"\u975e\u5178\u578b\u5f02\u6b65":43,"\u9879\u76ee\u5916":43,"\u9879\u76ee\u6216\u591a\u6216\u5c11\u90fd\u4f1a\u9047\u5230":43,"\u9879\u76ee\u7684\u8d21\u732e":43,"\u9886\u57df\u7684\u7a7a\u767d":43,"\u9ad8\u6027\u80fd\u6a21\u677f\u9879\u76ee":43,"abstract":[4,24,33,41],"boolean":[11,29,33],"break":[1,3,15,41,44],"case":[2,3,4,6,10,12,13,14,15,21,26,41],"class":[2,6,7,10,11,12,13,14,21,22,23,24,26,27,28,29,32,33,34,35,36,38,41,43,44,45],"default":[2,3,4,6,7,8,11,12,13,14,15,19,21,23,24,26,27,29,32,33,38,39,41,44,45],"enum":[26,27,41],"export":[6,8],"final":[1,2,4,10,29,41,44,45],"float":[11,26],"function":[2,8,11,20,22,26,27,29,33,44],"ila\u00ef":41,"import":[1,2,3,4,6,7,10,11,12,13,14,20,21,24,31,33,35,38,39,41,43,44,45],"int":[11,15,38,44],"long":[1,2,3,4,15,29,38,39],"micha\u0142":41,"new":[1,2,3,4,6,7,8,10,12,14,21,22,23,24,26,29,33,35,38,41,42,45],"null":[2,41],"public":14,"ram\u00edrez":43,"return":[1,2,3,4,7,10,11,12,14,15,21,22,23,24,26,27,29,33,35,38,39,41,44,45],"sebasti\u00e1n":43,"short":[2,3,4,7,14],"static":[28,44],"super":[4,12],"switch":[1,2,3,21,41],"transient":2,"true":[2,3,4,6,7,10,11,12,14,15,21,23,24,26,27,28,29,33,34,38,39,41,43,44,45],"try":[1,2,3,4,10,15,29,36,41,44,45],"var":8,"while":[1,2,4,10,12,14,21,23,29,36,41,45],"za\u0165ko":41,Added:[7,19,24,41],And:[1,2,3,6,7,8,11,12,23,41,44,45],Being:4,But:[1,2,3,4,12,44],Doing:4,For:[1,2,3,4,8,10,12,14,21,23,29,33,36,41,44,45],IDE:43,IDs:12,INTO:[15,45],NOT:[12,24],Not:[10,16,24,33,43,45],One:[1,5,6,29],PRs:44,That:[1,2,3,4,6,12,15,38,44,45],The:[0,2,4,7,8,10,11,12,13,14,15,21,22,23,24,26,27,29,33,36,38,39,41,43,44,45],Their:24,Then:[2,3,4,7,8,12,14,29,44,45],There:[1,2,3,4,13,14,29,41,45],These:[4,7,41],Use:[5,10,23,45],Used:[24,41],Using:[10,11,12,38],WITH:8,Will:44,With:[1,2,3,4,12,23,44,45],Yes:2,__all__:41,__attr_factory__:24,__init__:[12,44],__main__:38,__metadata__:24,__model__:41,__name__:[24,38,44],__repr__:38,__table__:[14,23,24],__table_args__:[24,41,45],__tablename__:[6,7,10,11,12,14,24,38,41,43,44,45],__values__:24,_base:27,_bind:10,_child:12,_children:12,_engin:[26,27],_event:[26,27],_floattyp:26,_idx1:45,_idx2:45,_integertyp:26,_is_metadata_oper:34,_lastrowid:26,_matchtyp:26,_name_idx:10,_numerictyp:26,_parent:12,_pk:45,_sa:26,_schematranslatemap:29,_test:44,_update_request_cl:41,abandon:41,abcd:8,abil:[12,41],abl:[3,4,44],abnormal_detect:11,abort:38,about:[1,2,4,6,8,10,14,15,22,23,29,41,45],abov:[1,2,3,4,7,10,12,33,44,45],absolut:[2,4],accept:[2,3,7,21,23,26,27,29,41,45],access:[0,2,3,10,14,15,24,29,36,38,41,44,45],access_log:11,accessor:26,accid:2,accord:[3,4,29,33,39],achiev:[1,10,12,14,21,29],acid:3,acquir:[2,3,4,14,21,26,27,28,29,36,38,41],acquisit:4,across:[7,33,44],act:[1,2,45],action:[8,36],activ:[7,8,29,44],actual:[1,2,3,4,7,12,14,15,23,24,29,38,44,45],adapt:[3,45],add:[1,2,3,4,6,8,10,12,21,22,23,31,41,42,45],add_child:12,add_us:44,added:[3,7,21,24,29,44,45],addit:[1,2,3,7,11,12,33],addition:[4,23],address:[6,14],adjac:10,adjust:44,admin:5,ado:7,adopt:41,advanc:5,advic:4,affect:[3,7,22,23,41,45],after:[1,2,3,4,6,7,14,15,21,23,24,26,27,29,33,38,41,44,45],after_get:11,afterward:[26,27],again:[1,2,3,4,10,12,29,44,45],against:8,age:[11,23,36],age_idx:11,aggreg:23,aintq:43,aiocontextvar:[2,5,17,18,19,41,43],aiohttp:[41,43],aiomysql:[17,18,19,25],aiomysqldbapi:26,aiomysqldialect:26,aiomysqlexecutioncontext:26,aiomysqliter:26,alemb:[5,11,14,21,42,43,45],alembic_sampl:6,ali:10,alia:[10,12,21,22,23,26,27,28,29,33,35,41],aliasload:33,alik:41,all:[1,2,3,4,6,7,8,10,11,12,14,15,21,23,24,26,28,29,33,36,38,39,41,44,45],all_us:45,allow:[1,2,3,14,21,24,26,27,41,44,45],alon:2,alpha:[10,41],alpin:[8,44],alreadi:[1,3,4,12,24,45],alright:1,also:[1,2,3,4,6,7,10,12,14,15,21,22,23,24,26,27,29,31,33,41,44,45],altern:[2,10,13,29,44,45],although:[3,12],alwai:[2,3,6,8,10,14,21,23,29,33,36,38,41,44,45],amaz:[10,45],among:3,amount:2,analysi:44,andrei:43,ani:[1,2,3,4,6,8,10,21,24,26,27,29,31,33,41],anoth:[1,2,4,12,22,23,29,33,45],answer:[1,3,10],anyth:[4,8,14,29,41],anywai:3,api:[0,2,4,5,10,14,17,19,22,26,27,29,36,42,43,45],apirout:44,apk:44,app:[4,10,13,38,39,41,44],appear:[1,3],append:23,append_where_primary_kei:23,appli:[2,3,5,14,23,29,36,43,44,45],applic:[4,7,10,21,39,41,44,45],appreci:8,approach:[1,3,4,7,10],arbitrari:4,archlinux:43,arg:[19,21,23,24,26,27,28,29,34,36],argument:[2,3,7,10,12,19,21,22,23,26,27,29,33,35,39,41,45],around:[3,29,43],arq:43,arrai:[11,27,41],arrayproperti:[11,32],arriv:1,arrrrh:1,articl:[3,8],artifact:44,asap:1,ascend:12,ascii_lett:[10,12],asgi:44,ask:[2,5],assembl:[2,12],assert:[15,24,36,41,44,45],assertionerror:41,assign:[2,26],assist:12,associ:[2,14],assum:[1,3,4,7,44],assumpt:[3,36],async:[0,1,2,4,7,10,12,14,15,21,23,26,27,28,29,34,35,36,38,41,43,44,45],async_execut:[26,27,28],async_main:3,asyncdialectmixin:[26,27,28],asyncenum:[26,27],asynchron:[0,2,3,12,14,15,16,21,29,36,45],asyncio:[0,1,2,3,5,12,14,16,20,43,45],asyncpg:[2,3,4,10,13,14,15,16,17,18,19,25,29,35,39,41,43,44,45],asyncpg_deleg:41,asyncpgcompil:27,asyncpgcursor:27,asyncpgdbapi:27,asyncpgdialect:[3,27],asyncpgexecutioncontext:27,asyncpgiter:27,asyncpgjsonpathtyp:27,asyncpgsa:[14,43],asyncschemadropp:34,asyncschemagener:34,asyncschematypemixin:34,asyncvisitor:34,ath:23,atom:23,attack:44,attent:38,attribut:[3,10,12,14,23,24,29,33,41,45],attributeerror:21,audienc:45,audit_profil:11,aur:43,austin:10,auth_plugin:26,authent:4,author:[4,21,43,44],author_id:43,auto:[0,11,23,24,44],autocommit:[0,4,26],autogener:[6,44],autom:[12,44],automat:[3,7,12,20,22,23,24,29,33,35,36,38,44],avail:[2,5,10,14,15,23,24,29,36,39,41,44],averchenkov:41,avoid:[3,4,33],awai:[2,4],await:[1,2,3,4,7,10,11,12,14,15,21,23,29,33,36,38,39,41,43,44,45],await_onli:3,awar:44,awesom:[1,43],back:[1,2,3,4,12,15,21,29,36,41],backend:44,background:[3,16],backport:[2,10,41,44],backward:41,bad:[3,41],bake:[5,19,21,22,41],baked_queri:[26,27,28],bakedqueri:[5,22],bakeri:[5,17,18,19,21,26,27],balanc:[4,23],bar:1,barancsuk:41,bare:[1,4,5],base:[3,6,10,12,13,17,18,19,21,22,23,24,25,26,27,29,30,32,33,34,35,36,44],base_exp:32,basedbapi:[26,27,28],baseexcept:[15,36],basemodel:44,basic:[2,3,4,5,23,42,43],batch:[5,23,45],bayer:[4,43],becaus:[1,2,3,4,7,10,14,15,21,23,36,41,44,45],becom:[2,3,14],been:[1,2,26,27,41],befor:[1,2,3,4,7,8,10,12,14,15,22,23,26,29,36,38,44,45],before_set:11,begin:[1,3,4,7,26,27,28],beginn:45,begun:3,behav:[23,41],behavior:[2,3,10,15,23,29,38,41],behind:[2,3,4,7,12,23,41,44],being:[1,2,3,4,14,23],belong:15,below:[8,10,11,44],benefici:4,besid:10,best:[1,8,41,44],beta:41,better:[4,41,43],between:[1,2,4,41],beyond:4,biginteg:[21,38,44],bin:44,binari:[28,41],bind:[2,4,7,10,14,15,21,22,23,26,27,34,41,45],bind_processor:[2,27],bindparam:7,bindtempl:27,binghan:41,birthdai:11,bit:[1,8,14,23,41,45],bite:[29,38],black:41,blade:1,blob:43,block:[1,2,3,4,15,29,36,38],blog:8,blue:2,bondar:43,book:[10,21,43,45],booker:45,bookings_idx_booker_room:45,bookings_idx_day_room:45,bookings_pkei:45,bool:[11,44],booleanproperti:[11,32],boost:[1,7],borrow:[2,15,29,38,39],boss:1,bot:43,both:[2,3,4,10,12,14,21,23,24,26,27,36,41,45],bottleneck:[1,4],bound:[1,21,23,24,26,38,45],boundari:3,branch:8,bridg:3,brien:41,broken:41,browser:8,brutal:1,bryanforb:43,bsd:16,buffer:[3,4],bug:[3,5,10,41,43],bugfix:8,build:[1,3,4,8,10,12,21,23,42],builder:[12,44],built:[3,10,14,16,22,23,24,29,39,41,44,45],builtin:[28,38,41],bulk:[4,5,29],bunch:6,bundl:21,busi:[1,4,14],bypass:3,c10k:1,cach:[7,44],calcul:26,call:[1,2,3,4,7,10,12,15,20,21,23,24,26,27,29,33,36,41,44,45],call_next:10,callabl:[12,26,27,29,33,41],callableload:33,callback:1,caller:10,came:4,can:[1,2,3,4,5,6,7,8,12,13,14,15,21,22,23,24,29,33,36,38,39,41,44,45],candid:41,cannot:[1,2,3,12,41,44],canopi:43,canopytax:43,cap:4,captur:44,care:3,carefulli:1,cast:[11,44],categori:12,categories_1:12,categories_2:12,caught:36,caus:[2,3,4,15,29,38,39,41,45],cdi:43,celeri:4,certain:[4,38],chain:[2,4,7,21,23,33,41,45],challeng:4,chanc:[1,4],chang:[3,6,8,10,19,23,24,29,41,44,45],characterist:3,charset:26,chat:4,check:[2,3,8,10,12,14,23,26,27,44,45],checkfirst:[26,27,34],checklist:44,checkout:8,child:[12,41],child_id:12,children:[12,36],chmod:8,choic:[4,10,12],choos:[4,19,41,45],classic:12,classmethod:[7,23,28,33],claus:[2,10,12,14,21,23,26,27,28,29,33,45],clean:[10,41,44],cleaner:[3,44],cleanli:[4,29],cleanup:39,clear:4,cli:44,click:2,client:[4,8,43,44],client_flag:26,clone:8,close:[2,3,4,15,21,22,26,27,28,29,36,38,41,45],closer:3,cls:[7,11,24],cmd:44,code:[1,2,3,4,10,12,14,15,16,29,36,41,44,45],coin:4,col:12,collect:[23,44],collid:41,color:[2,26,27,28,29],colspec:[26,27],coltyp:[26,27],column:[2,5,6,7,11,12,14,21,23,24,26,27,29,33,38,41,43,44,45],column_kei:27,column_nam:23,columnattribut:24,columnload:[10,12,33],com:[8,10,16,43,44],combin:[2,12,45],come:14,command:[3,4,6,44,45],command_timeout:27,comment:[3,7,29],commit:[0,4,8,15,26,27,28,29,36,41,44],common:[7,14,15,29,39,44],commun:[3,16,43],compani:33,compar:[1,4,23,44],compat:[2,3,10,29,33,41],compil:[7,21,22,28,29,45],compiled_sql:22,complet:[2,10,21,41,44],complex:[1,5,7,12,43,45],compli:3,compliant:3,complic:[0,1],compos:[44,45],composit:23,comput:1,con:0,concentr:4,concept:[2,14,45],conceptu:14,conclus:4,concret:[2,14,24,38],concurr:[1,3,4],condit:[12,23,45],config:[10,13,38,39,41,44],configur:[8,17,33,37,38,44],confirm:41,conflict:[3,12,33],conftest:44,confus:2,congratul:6,conn1:2,conn2:2,conn:[2,3,4,14,21,26,27,28,29,36,41],connect:[0,3,4,5,7,12,14,15,17,19,21,22,26,27,29,34,36,37,38,41,42,44],connect_timeout:26,connection_cl:29,connection_class:27,connectionless:2,conradi:41,consid:[3,4,10,41],consist:41,constant:1,constantli:[3,7],constraint:[24,34,41,45],construct:[4,7,10,14,21,24],consum:[3,4],contain:[3,6,10,24,45],content:[1,17,18],context:[1,2,3,4,10,15,16,21,22,26,27,28,29,33,36,38,39,41,43,44],contextu:[10,12,22,38],contextualgino:10,contextvar:[2,10,17,20,43],continu:[15,36],contrast:[1,4],contribut:[5,41],control:[1,3,5,26,27,29,38,41,44],conv:26,conveni:[2,3,4,14,15,21,23,43,44,45],convers:[2,26,27],convert:33,cool:1,cooper:[0,4],copi:[3,10,29,41,44],core:[1,2,3,5,7,10,16,21,22,24,41,43,45],coroutin:[1,2,3,4,23,29,35],correctli:[3,4,14,15,21,23,41,44],correspond:[2,12,22,23,24,26],correspondingli:[2,15,36],cost:1,could:[1,2,3,4,7,8,10,12,22,23,44],count:[2,10,12,44,45],count_1:45,cours:44,cov:44,cover:[41,44,45],coverag:[41,44],cpu:1,cpython:43,creat:[0,3,4,5,7,8,10,12,14,15,19,21,22,23,24,26,27,29,33,34,35,36,38,39,41,42,43],create_al:[3,7,10,11,12,14,21,34,41,45],create_async:[26,27,34],create_async_engin:3,create_engin:[2,3,4,7,10,13,14,19,21,26,29,33,35,41,45],create_ok:34,create_pool:[2,41],create_t:44,create_task:10,createdb:[44,45],creation:[2,7,10,21,22,41,44],credenti:6,credit:8,critic:1,cross:38,crt:8,crucial:15,crud:[2,4,5,10,12,14,17,18,19,21,29,41,42,43],crudmodel:[21,23,41],csrf:44,ctrl:44,ctx:12,cur:44,curatedlist:43,current:[1,2,3,10,13,15,19,23,26,27,29,41,44,45],current_connect:[0,29,41],current_databas:10,current_us:[4,43],cursor:[2,3,26,27,28,29],cursor_cl:[26,27,28],cursorclass:26,custom:[3,5,11,12,23,24,29,41],customiz:[24,41],cut:4,cutil:41,cve:44,dahlia:43,dai:45,daisi:[11,24,43,45],damn:1,danger:38,darwin:44,data:[1,2,3,10,11,12,23,44,45],databas:[0,2,3,5,6,7,8,11,12,14,15,19,21,23,24,26,27,29,33,36,38,39,41,43,44,45],datastructur:44,date:45,datetim:[10,11,12,24,33],datetimeproperti:[11,32],db_age:23,db_databas:[38,44],db_driver:44,db_dsn:44,db_echo:[10,38,41,44],db_host:[13,38,44],db_kwarg:[13,38],db_name:[6,8],db_pass:8,db_password:[38,44],db_pool_max_s:[38,44],db_pool_min_s:[38,44],db_port:[8,38,44],db_retry_interv:44,db_retry_limit:44,db_ssl:44,db_time:7,db_use_connection_for_request:[38,44],db_user:[8,38,44],dbapi:[26,27,28],dbapi_class:[26,27,28],dbapi_conn:[3,26,27],dbapicursor:[26,27,28],dbname:[10,44],ddl:[34,44],dead:4,deadlock:[3,4],deal:[1,4,10,12,15],debug:[1,38],decent:3,decid:3,decim:41,declar:[1,5,12,17,18,19,21,23,42],declarative_bas:24,declared_attr:[7,11,24,41,45],decod:32,decor:[7,24],decreas:1,deeper:3,def:[1,2,3,4,7,10,11,12,14,24,26,27,38,44,45],default_isolation_level:26,defaultdialect:[26,27],defer:4,defin:[3,5,6,7,11,12,13,14,21,24,29,33,44,45],definit:[10,12,24,44],del:10,delai:4,deleg:[2,14,21,23,41],delet:[12,14,23,41,42,44],delete_us:44,deliv:[1,3],demand:7,demo:44,demonstr:44,depend:[1,2,4,6,7,10,23,29,36,41,42,45],deploi:[4,44],deprec:[3,23,33,41],describ:[4,10,16],descript:[6,8,26,27,28,39,44],design:[2,3,4,10,45],detach:45,detail:[2,8,10,12,45],detect:44,determin:[4,12],deutel:41,dev:[43,44],develop:[6,8,17,38,44],diagram:[1,2,44],dialect:[2,3,10,11,13,16,17,18,19,22,29,34,36,39,41,45],dict:[2,10,11,13,23,24,33,41,44],dictionari:[2,29,38],did:41,didn:[2,4,31],differ:[1,2,3,4,5,11,12,14,21,23,24,29,41,44,45],difficult:1,dig:14,direct:[4,26,29,45],directli:[2,3,4,7,10,12,14,21,23,24,26,29,38,41,44,45],directori:[6,41,44],dirti:[10,41],disabl:[23,41],disable_inherit:41,disable_task_loc:41,disadvantag:4,disallow:10,disast:[15,38],discard:[2,23,29],disconnect:45,discord:43,discourag:4,discuss:10,disproportion:4,dist:41,distinct:[12,23,33,41],distinguish:2,divio:16,django:5,do_load:33,do_on_connect:[26,27],doc:[3,6,8,10,15,41,43,44],docker:[8,44],dockerfil:44,docstr:8,document:[2,3,5,6,7,10,41,43,44,45],doe:[2,3,4,5,12,14,21,23,29,33,41,43,45],doesn:[2,3,4,10,11,12,24,41,44,45],doge:3,doing:[1,4,7,21,41],don:[0,1,2,3,5,10,12,15,23,29,44,45],done:[0,1,2,6,8,10,14,15,22,41,44,45],doubl:1,doubt:12,down:[4,44],downgrad:[6,44],download:16,dramat:1,driven:8,driver:[2,3,10,15,26,27,29,39,41,45],drivernam:44,drop:[1,34,41,44],drop_al:[3,10,12,34],drop_async:[26,27,34],drop_ok:34,drop_tabl:44,dsn:[39,41,44],due:[4,41,45],dure:[1,2,22,24,29,38,41],dynam:[12,14,24],dziewulski:41,each:[1,2,3,4,6,7,10,12,22,24,29,33,38,45],earli:[3,15,16,17,36,39],earlier:[3,10,39],easi:[2,3,10,12],easier:[1,3,7,8,10],easili:[1,2,3,4,12],echo:[2,3,10,29,39,41,44],ecosystem:[3,4],edg:1,edit:11,effect:[19,23,29,45],effici:[1,2],effort:4,either:[1,2,3,4,6,7,10,14,15,23,29,36,44],elem:[21,22,28],element:21,els:[2,3,4,10,14,15,29,38,44,45],email:[4,10],email_address:14,emerg:41,emit:3,empti:[2,38,39,41,44],enabl:[2,8,10,23,24,33,39,41,44],enable_inherit:41,enable_task_loc:41,encapsul:[3,4,10,44],encod:[32,43],encourag:21,encrypt:8,end:[2,3,4,12,15,44,45],endpoint:4,enforc:[3,12,15],engin:[0,1,3,5,15,17,18,19,21,22,23,26,35,36,39,43,44,45],engine_cl:35,engine_from_config:21,enginestrategi:35,enhanc:[4,8,41],enjoi:38,enough:[4,44],ensur:41,enter:[15,21,29],entri:[14,31,44],entry_point:44,enumer:26,env:[6,10,44],environ:[8,41,44],equal:[2,23,41],equival:[23,24,26],error:[3,10,27,28,41],especi:[1,2,4,10,12,41,45],establish:38,etc:[3,7,26,27,44],even:[1,2,3,4,7,8,10,14,21,23,24,29,38,41,44,45],event:[1,3,4,8,26,27,41,43],eventlet:43,eventu:[2,3,10,44],ever:[3,36],everi:[1,7,8,12,23],everyon:2,everyth:[2,3,4,10,14,15,38,45],evil:3,exactli:[2,12,21,29,45],exampl:[1,2,3,4,6,7,8,10,12,13,14,15,21,23,29,33,36,38,41,44,45],except:[1,2,3,10,15,17,18,19,27,28,29,36,38,39,41],exchangeratesapi:43,excit:3,exec:8,execut:[0,3,4,5,7,11,12,14,21,22,23,26,27,28,29,33,39,41,45],execute_bak:[26,27,28],executemani:[28,29,41],execution_ctx_cl:[26,27],execution_opt:[2,3,7,10,12,21,22,23,26,29,33,41],executioncontextoverrid:[26,27,28],exhaust:[2,4],exist:[2,3,4,5,21,23,24,26,27,39,41,45],exit:[15,21,29,36],exp:11,expect:[3,33],experiment:[12,23,33],explain:[3,4,8,10,12,16,44],explan:[16,43],explicit:[0,2,3,10,12,15,26,41,43,45],explicitli:[2,3,4,7,10,11,36,38,45],explict:14,expos:[14,21,41],exposur:3,express:[5,11,23,29,33],ext:[3,10,13,17,18,19,21,38,39,41,44],extens:[2,7,10,13,14,17,21,31,38,39,41,42,45],extern:[1,45],extra:[1,3,33,41,44],extract:41,extrem:2,f2c273a43a3ed893a767d4239046f2befabf510d:43,face:4,facebook:43,facil:26,fact:[3,10,26,27],factori:[22,24,39,44],fail:[2,21,41,44],fair:1,fals:[2,3,4,7,11,14,23,24,26,27,28,29,34,38,39,41,44],familiar:45,famou:1,fantix:[23,43,44,45],far:[3,14,45],fast:[4,38,43,44],fastapi:[4,10,42,43],faster:[7,22,45],featur:[2,3,5,12,23,33,41,44,45],fed:[7,12,41],feed:[1,29,33,44],feedback:5,feel:[1,3,23,29,44,45],fetch:[1,29],fetchal:3,fetchval:3,few:[2,4,10,29,38,41],field:[10,11,14,23],file:[1,6,8,41,44],fill:33,filter:[23,45],find:[3,4,6,24,31,45],fine:[3,4,10,14],finish:[1,2,4,6,23,29,38,44],first:[1,2,3,4,5,7,8,10,12,14,19,21,23,26,27,28,29,33,38,39,41,44,45],first_connect:[26,27],first_nam:10,first_or_404:41,firstli:12,fit:2,five:41,fix:[3,4,5,10,41,44,45],fixtur:44,flag:[26,27,39],flake8:8,flat:10,flexibl:[11,12,43],flow:4,flush:4,fly:5,focu:10,folder:6,follow:[2,3,4,10,11,15,21,33,36,44,45],footprint:1,forc:[1,4],foreign:[10,12,23],foreignkei:[10,12,14,43],forev:[3,23,29],forget:[2,3,45],fork:8,format:[10,26,38],former:2,fortun:4,forward:[12,26,27,28],found:[2,4,10,12,21,22,24,41,44,45],foundat:[4,43],founder:45,founding_us:45,fouser:21,framework:[1,7,10,41,44],free:[4,16,23,29,44,45],freebsd:43,freez:4,frequent:[5,12],friendli:[41,45],from:[1,2,3,4,6,7,10,11,12,13,14,15,16,21,22,23,24,29,33,36,38,39,41,43,44,45],fromclaus:33,frozen:44,frustrat:3,full:[2,6,10,44],full_path:6,fulli:[29,44,45],fullnam:14,fun:[4,45],func:[10,12,33,45],func_or_elem:[21,22],fundament:[3,4],further:[2,3,7,14,29,45],furthermor:[2,7,29,38],fut:10,futur:[3,10,12,44],gain:12,galden:41,garciasilva:43,gbasic:43,gcc:44,gener:[1,2,11,12,23,24,26,27,33,44],geoalchemi:43,get:[1,2,3,4,5,7,10,12,14,16,19,21,22,23,24,29,33,38,41,42,43,44],get_affected_row:[26,28],get_app:44,get_column:33,get_current_connect:41,get_event_loop:45,get_from:33,get_isolation_level:[26,27],get_lastrowid:[26,28],get_loc:41,get_now:2,get_or_404:[38,41,44],get_profil:32,get_raw_connect:29,get_result_proxi:28,get_statusmsg:[26,27,28],get_us:[38,44],get_vers:19,getattr:44,getlogg:44,getter:[7,21],gevent:43,gino:[2,3,4,5,6,8,11,12,13,15,17,18,38,39,42],gino_db:8,gino_fastapi_demo:44,gino_fastapi_demo_test:44,gino_starlett:31,ginoconnect:[2,14,15,17,22,29,36],ginoengin:[2,10,14,15,21,22,23,29,33,35,36,41],ginoexcept:30,ginoexecutor:[2,7,21,22],ginonulltyp:[26,27],ginopool:41,ginoschemavisitor:[14,21,34],ginostrategi:35,ginotransact:[15,29,36,41],git:[8,29,44],github:[8,10,16,43],gitignor:44,gitlab:43,gitter:16,give:[1,3,4,12,22,33],given:[2,3,8,10,12,21,22,23,24,26,27,29,33,35,44],global:[7,14,21,45],gmail:44,gnu:43,goe:45,going:3,golden:4,goncharov:41,gone:41,good:[1,3,29],got:1,gotta:1,grab:3,grai:2,grammar:[4,10,41],grandson:12,grant:3,great:[4,6,10],greater:[1,20],greatli:[1,2,3,8],green:[1,2],greenlet:[3,10],greenlet_spawn:3,group_bi:[10,12],guarante:[4,15,29,44],guess:4,guess_model:41,guid:[16,44,45],guidelin:5,gunicorn:44,hack:[10,44,45],had:[1,14,24],hadn:1,hand:[1,2],handl:[1,2,4,15,29,36,41],handler:38,hang:[3,4],happen:[1,3,4,21,29,45],happi:44,hard:4,hardwar:4,harm:4,has:[1,2,3,4,7,10,12,14,15,19,21,22,23,26,27,29,41,45],has_schema:27,has_sequ:27,has_tabl:[26,27],has_typ:27,hash_:22,haunt:[3,4],have:[1,2,3,4,6,7,10,12,14,15,23,33,36,39,43,44,45],haven:44,head:[2,6,44],heavi:3,hei:[1,4],height:11,help:[0,1,8,15,45],helper:7,henc:21,here:[1,2,3,4,7,8,10,11,12,14,15,23,29,36,41,44,45],herebi:21,hidden:[2,3],hide:[2,41],hierarch:[10,12],hierarchi:44,high:[1,4,7],higher:44,histori:17,hit:4,hmm:2,hold:[1,3,10,15,44],holubakha:41,hong:43,honor:44,hood:[2,23,45],hook:[5,10,21,26,27,31],hoorai:3,host:[26,27,39,44],how:[0,1,2,3,6,8,12,15,16,29,43,45],howev:[1,2,3,4,10,14,21,23,29,41],html:43,http:[1,6,8,10,16,29,43,44],hurri:1,hybrid:4,hyper:1,id_val:10,idea:[3,4],ideal:[1,45],ident:[2,3,12,14,23,41,45],identifi:4,idl:[3,4],ignor:[22,44],imag:44,imagin:[1,3],immedi:[2,4,7,19,23,29,36],immut:2,impair:1,impl:44,implement:[2,3,5,24,26,33,44,45],implic:14,implicit:[0,3,4,10,15,21,26,41,43],implicitli:[2,4,7,10,14,15,29,36],importantli:4,importlib:44,imposs:4,improv:[1,41],in_:12,in_queri:23,inc:43,includ:[3,8,10,23,39,41,44,45],include_foreign_key_constraint:34,include_rout:44,incomplet:44,increment:23,index:[1,5,12,24,34,43,45],index_on_nam:10,indic:[24,33,45],individu:[2,3,23,44],infer:23,info:44,inform:[2,7,10,14,15,21,22,29,45],inherit:[2,7,10,15,22,23,29,41,45],ini:[6,44],init:[6,26,27,41,44],init_app:[13,38,39,44],init_command:26,init_kwarg:[26,27],init_pool:[26,27,28],initi:[2,3,5,7,11,14,23,24,26,27,33,35,39,44],initializederror:30,inject:[2,14],inlin:[14,21,27,41],inner:[2,15,26,27],ins:14,insert:[3,5,14,15,23,26,29,41,43,45],insid:6,insist:12,inspir:[12,14],instal:[6,8,39,41,42,44],instanc:[2,4,6,7,10,11,12,14,15,21,22,23,24,26,27,29,32,33,35,41,44,45],instant:23,instanti:[14,23,29,33,44],instead:[1,2,3,4,12,14,15,23,24,29,31,41,44,45],integ:[6,7,10,11,12,14,24,43,45],integerproperti:[11,32],integr:[5,38,41,42],intend:24,intens:[1,4],interact:[44,45],interest:3,interfac:[2,3,5,21,33,41],interfaceerror:27,interfer:41,interim:3,interleav:1,intern:[2,10,12,15,22,23,24,36,41],internet:4,interpret:[12,36],interrupt:1,interv:27,introduc:[3,10,12,41],introduct:42,intuit:4,invalid:38,invent:10,invers:44,invert_get:24,invertdict:24,invok:[23,26,27],involv:[10,14,26],irrelev:21,is_:23,is_local_root:41,isdigit:38,ish:4,isol:[0,2,26,27,29,41],isolation_level:[2,3,26],issu:[3,4,8,10,11,26,41,43,44],item:[12,14,33,34,44],iter:[2,3,10,12,14,21,23,24,26,27,28,29,41,43],its:[1,2,3,4,10,12,21,23,24,26,27,29,33,36,39,41,45],itself:[1,2,3,4,10,12,14,15,24,26,27,44],iuliia:41,jack:14,java:43,jeff:10,jekel:41,jetbrain:43,jim:41,job:29,join:[5,12,21,23,33,41,43],join_queri:12,join_without_n_plus_1:4,jone:[14,43],json:[5,23,26,27,38,41,44],json_support:[17,18,19,23],jsonb:[11,41],jsonindextyp:26,jsonpathtyp:[26,27,41],jsonproperti:[11,23,32],julio:41,just:[1,2,3,4,6,10,12,14,15,23,24,36,38,41,44,45],keep:[1,3,4,8,10,12,26,41,45],kei:[8,10,12,23,24,26,33,41,45],kentoseth:41,kept:[4,33],keyout:8,keyword:[2,3,7,10,12,19,22,23,33,45],kill:[1,4],kind:4,king:[43,44],kinwar:41,know:[1,2,3,4,10,15],knowledg:[12,14,23,45],known:[2,12,44,45],kooten:41,kovalev:41,kubernet:44,kwarg:[19,21,22,23,24,26,27,28,29,34,35,36,39,41],label:[33,41],lacerda:41,lambda:12,larg:[3,4,29],larger:[1,44],last:[1,2,4,12,21,23,36,44,45],last_nam:10,lastli:3,lastrowid:26,later:[1,2,10,12,14,29,39],latest:[23,29,43,44],latter:2,law:4,layer:4,layout:[41,44],lazi:[0,3,10,17,29,37,38,41],lazili:[2,7,19,38],lazy_engin:10,lead:[3,4,11],leaf:12,learn:[2,4,22],least:[1,4,7],leav:[3,29],led:29,left:[2,3,12,23,43],legaci:14,len:12,length:14,lengthi:4,leosussan:43,less:[1,2,4,14],lesson:16,let:[1,2,3,4,7,12,14,15,44,45],level:[0,2,4,7,10,11,14,23,24,26,27,29,45],leverag:[3,4,11],lib:[8,44],libffi:44,librari:[3,41,43,44,45],licens:[16,43],liebig:4,lifetim:38,lightn:44,lightweight:[6,16],like:[1,2,3,4,6,7,8,10,11,12,14,23,24,29,31,38,39,44,45],likewis:[2,12,33,45],limit:[1,3,4,26,27,28,41,45],line:[2,6],linearli:1,link:[3,4,6,10,44],list:[2,8,10,11,14,29,33,44,45],listen:[3,4,26,27],liter:[1,29],littl:[1,8],live:[1,44],load:[2,3,4,5,7,12,21,23,29,33,41,43,44],load_modul:44,loader:[5,10,17,18,19,21,23,28,29,41,43],lobbi:16,local:[2,6,8,17,44],local_infil:26,localhost:[3,4,7,8,10,12,13,14,33,38,39,44,45],locat:[23,41],lock:[3,4,44],log:[44,45],logger:44,logging_nam:[2,29],logic:[1,3,4,44],login:8,longer:[1,2,4,10,29,41],look:[1,4,8,12,23,39,44],lookup:[23,41],loop:[1,3,10,21,26,27,28,29,35,41,43],lose:29,lost:4,lot:[1,3,4,12],love:4,low:[4,7],lower:[1,3,10,45],luckili:3,made:[3,10,12,14,41,44,45],magic:[2,3,7,12,45],magicstack:[10,43],mai:[1,2,3,4,10,11,12,15,21,22,26,29,38,44,45],main:[2,3,4,6,7,10,12,14,44,45],main_app:6,maintain:[3,4,10,24,43,44],mainten:[3,41],major:4,make:[1,2,3,4,6,7,8,10,12,23,26,27,29,38,44,45],make_express:32,make_url:44,manag:[0,1,3,7,15,21,29,36,38,41,44,45],mandatori:14,mani:[2,3,4,5,8,10,26,27,28,29,41,45],manipul:41,manual:[3,5,10,11,12,14,23,29,36,41,44],map:[2,10,12,14,43,44,45],mapper:10,marissa:10,mark:[4,24,29],martin:41,masonri:44,mass:45,massiv:23,master:43,match:[3,12],matchtyp:26,matter:[2,3,12,14],max:[2,44],max_cacheable_statement_s:27,max_cached_statement_lifetim:27,max_inactive_connection_lifetim:27,max_overflow:4,max_queri:27,max_siz:27,maximum:39,maxsiz:26,mayb:3,mean:[1,2,4,12,15,23,24,26,27,29,41,45],meaningless:[2,24],meant:[2,45],meanwhil:[7,23,36,41],meet:8,member:45,memori:[1,2,10,23,24,29,45],mention:[1,2,3,14,44,45],mess:[1,21],messag:[4,41],met:45,meta:3,meta_path:31,metaclass:23,metadata:[2,7,10,14,21,22,23,24,34,41,43,44,45],method:[2,3,4,7,14,21,22,23,24,26,27,29,33,36,41,45],michael:43,middl:[1,39],middlewar:[10,39,41],might:[1,2,3,8],migrat:[5,17,44],mike:4,mimic:3,min:44,min_siz:[2,27],mind:1,minhe:43,minim:[1,14],minimum:4,minsiz:26,misc:41,miser:4,miss:[2,3,41],mission:4,mistak:41,mix:[3,4],mixin:[24,41,45],mkdir:44,mkvirtualenv:8,mock:33,mod:44,mode:[2,3,4,26,27,29,36,39,44],model:[2,4,5,6,7,10,11,14,21,23,24,28,29,33,38,41,42,43],model_base_class:21,model_class:[21,24],model_kei:10,modelload:[10,12,33,41],modern:4,modif:45,modifi:[3,12,44,45],modul:[2,6,10,17,18,41,44],modulenotfounderror:6,moment:[1,2,4],more:[1,2,3,4,7,8,10,12,14,15,21,22,23,24,29,41,45],morgan:41,most:[2,3,4,10,14,15,23,26,29,41,45],mostli:[3,4,23],move:[3,41,45],much:[1,2,3,4,11,14,15,29],multi:1,multiparam:[2,21,28,29,41],multipl:[1,2,5,12,21,22,29,33,41,45],multipleresultsfound:[29,30],multiplex:1,multitask:[0,4],musl:44,must:[1,2,3,4,6,10,14,21,29,33,44,45],mutabl:41,my_app:6,myapp:44,mydb:44,mydb_test:44,mydialect:[26,27],mykyta:41,mymodel:44,myself:[1,4],mysql:[10,26,43,45],mysqlcompil:26,mysqldialect:26,mysqlexecutioncontext:26,mytab:15,mytabl:15,myuser:23,name:[1,2,3,4,6,7,8,10,11,12,14,21,23,24,33,35,38,39,41,43,44,45],name_or_url:35,namespac:31,narrow:8,nativ:[3,11,41],natur:[1,4],neal:41,nearli:1,neat:4,neath:3,necessari:[1,4,26,27,38],necessarili:2,need:[1,2,3,4,6,7,8,10,11,12,14,15,19,21,29,38,39,41,44,45],neither:22,nest:[2,3,5,12,29,33,36],network:[1,2,4],never:[1,4,14,15,29,45],nevertheless:4,new_child:12,new_nam:10,new_names_dict:10,newcom:16,newer:3,newli:[23,26,27,45],next:[1,3,4,6,14,26,27,28,29,44],nicknam:[6,14,38,44,45],no_delai:26,no_deleg:21,non:[1,10,13,14,29,41,45],nonam:[6,14,45],none:[2,3,10,12,14,21,22,23,24,26,27,28,29,32,33,34,35,39,41,44,45],none_as_non:[17,23,33],nor:22,noresultfound:[29,30],normal:[2,3,4,7,11,12,14,15,21,23,24,36,44,45],nosuchrowerror:30,note:[2,3,12,19,26,29,38,41,42,45],noth:[1,2,3,4,10,15,33,41],notic:[1,2,12],now:[1,2,3,4,6,7,8,10,12,14,15,16,21,29,33,41,44,45],nullabl:[11,14,44],nullpool:[13,27,41],nulltyp:[26,27],number:[2,4,11,23,39,44],numer:[26,28],obj:34,object:[2,3,4,6,7,10,11,12,14,21,22,23,24,26,27,28,29,32,33,34,36,41,43,44,45],objectproperti:[11,32],obviou:[1,4],obvious:[4,41],occasion:[4,21],occur:[1,26,27],odd:3,off:[2,3,4,38,41],offer:[2,14,36,41],offici:[6,8,21,31],often:[21,23,24],okai:[1,44],olaf:41,old:[3,23,43],olexii:41,omit:[12,23],on_claus:[23,33],on_connect:[26,27],onc:[1,2,4,6,10,12,22,24,26,27,29,45],one:[1,2,3,4,7,10,12,14,16,21,23,26,27,28,29,33,41,45],one_or_non:[2,7,14,21,29,41],ones:[2,3,4,21,33,44,45],onli:[1,2,3,4,6,7,12,13,14,15,16,21,22,23,24,26,29,33,36,39,44,45],ons:2,open:[3,6,8,15,29,43],openid:4,opensourc:43,openssl:[8,44],oper:[1,2,4,8,21,23,24,29,41,42,43,44],opposit:[4,29],ops:3,opt:29,optim:2,option:[1,2,3,7,10,12,13,21,22,23,26,27,29,33,41,44],order:[1,2,3,10,12,23,29,44,45],ordinari:12,org:[6,43],origin:[3,8,14,23],orm:[0,2,3,5,12,16,43,45],orphan:2,orz:43,oss:43,other:[1,2,3,4,5,6,8,13,14,15,21,23,24,29,33,39,41,44,45],otherwis:[24,26,27,29,45],our:[1,4,6,44,45],out:[1,2,4,8,14,24,29,45],outer:[2,12,15,23],outerjoin:[10,12,33,41,43],output:[3,12,14],outsid:[1,45],over:[4,44],overal:[4,12],overhead:[1,4],overlap:1,overload:4,overrid:[7,21,23,24,41,44],overwrit:[3,44],own:[1,2,4,10,12,13,14,44,45],owner:8,packag:[6,17,18,39,41,43,44],page:1,pai:38,pair:[12,23],parallel:[1,2],param:[21,28,29],paramet:[2,5,7,14,21,22,23,24,26,27,28,29,33,39,41,45],paramref:26,paramstyl:[2,26,28],parent:[2,10,12,14,21,36,41],parent_id:[10,12,41],parents_x_children:12,parentxchild:12,pars:[29,41],part:[1,2,3,4,8,10,26,44,45],partial:[2,10,41],particular:[26,27],particularli:23,pascal:41,pass:[1,7,8,26,27,29,33,39,41,44],passfil:27,passin:8,passiv:41,passout:8,password:[6,8,26,27,39,44],patch:[10,20,41],patch_asyncio:20,patch_schema:34,path:44,pattern:[4,10,12],paus:1,pavol:41,payload:2,pem:8,pend:[3,17,23],peopl:[3,4,12],pep:[3,41,43],per:[3,26,27,29],perform:[1,4,7,10,38],perman:[2,3,29,39,41],persist:3,person:3,peter:43,pgcompil:27,pgdialect:[3,27],pgexecutioncontext:27,pgjone:43,phase:44,philip:43,pictur:3,piec:[1,12,45],pip:[6,8,39,41,44,45],place:[3,24,26,29,41],plai:[2,4,21,29],plain:[2,10,43],plain_old_java_object:43,platform:[4,44],pleas:[1,2,3,7,8,10,11,12,14,15,19,21,29,38,41,44,45],plu:[7,21],plugabl:44,pluggi:44,plugin:44,plural:45,poetri:[6,41,44,45],point:[1,3,4,29,31,44],poli:24,pool:[2,3,4,5,7,22,26,27,28,29,38,39,41,44],pool_class:[13,26,27,28],pool_max_s:[39,44],pool_min_s:[39,44],pool_recycl:26,poolev:[26,27],pop_bind:[2,21,41,45],popo:43,popul:[23,45],popular:[44,45],port:[3,4,14,26,27,39,44],posit:[7,23,26,27,29,33],possibl:[1,2,3,4,6,7,8,12,14,22,26,27,33,38,41,44,45],post:[2,3,8,12,44],post_exec:26,postfetch_lastrowid:26,postgi:43,postgr:[6,8,10,35,38,39,44],postgreserror:27,postgresql:[2,3,4,7,8,10,11,12,13,14,21,27,33,35,36,41,43,44,45],postgresqlimpl:44,postprocess:29,potenti:[3,12],power:45,practic:[1,3,4,29,45],pre:[3,19,22],prebak:[7,19,26,27],predict:1,preemptiv:1,preexecute_autoincrement_sequ:26,prefer:[4,26,33,38,45],prefetch:41,prefix:35,prepar:[5,6,19,22,26,27,28,29,41],preparedstat:[27,28],present:[2,12,29,41],press:44,pretti:[4,14],prevent:[7,41],previou:[1,2,12,14,21,39,41],previous:[1,2,12,44,45],primari:[23,26,41,45],primary_kei:[6,7,10,11,12,14,21,24,38,43,44,45],primarykeyconstraint:[44,45],primit:3,princip:[3,4],print:[3,5,7,11,12,14,23,43,45],prioriti:[4,44],privkei:8,pro:0,probabl:[2,3],problem:[1,3,4,6,16,41],proce:[26,27],process:[1,2,12,26,27,41,44,45],process_row:28,processor:[12,41],procur:26,produc:[2,12],product:[0,42],profil:[11,32,41],program:[0,2,3,4,12,15,45],program_nam:26,progress:2,prohibit:15,project:[6,8,10,42,45],promis:12,prop_nam:[11,24,32],propag:15,proper:[3,4,22],properli:44,properti:[2,4,5,6,10,12,14,21,22,26,27,28,29,33,36,41,45],propos:8,protect:41,provid:[1,2,3,7,10,11,12,14,15,21,22,23,29,31,33,39,41,44],proxi:[23,26],psql:8,psycopg2:[2,3,44],psycopg:44,publicli:[21,29],pull:5,pure:[10,41,45],push:8,put:[2,3,8,14,36],pwd:8,pycharm:43,pydant:44,pypi:[16,41],pyproject:44,pytest:[8,44],python:[1,2,3,4,6,8,10,11,16,20,24,31,41,42,44,45],pythongino:43,pythonpath:[6,44],qbasic:43,qualiti:4,quart:[41,43],queri:[0,4,5,8,11,12,14,17,19,21,22,23,24,26,27,28,29,33,39,43,45],query_cl:22,query_executor:21,query_ext:21,query_param:10,querymodel:23,question:[3,4,5],queue:[3,4,22],quick:[5,44],quickli:[3,10],quit:[2,3,4,10,14,23,44,45],qulaz:41,rais:[2,10,15,21,29,36,41],raise_commit:[15,36],raise_for_statu:44,raise_rollback:[15,36],raiseerr:44,ran:1,randint:[10,12],random:[10,12],rang:[10,12,41],rather:[1,4,10,23,45],raw:[1,2,4,5,12,13,14,22,29,33,41,45],raw_conn:[26,27,28],raw_connect:[29,41],raw_pool:[26,27,28,29,41],raw_transact:[15,26,27,28,36],rdbm:[38,45],reach:[36,38],reaction:4,read:[1,2,3,10,21,22,23,24,29,45],read_commit:3,read_default_fil:26,read_default_group:26,read_root:4,readabl:1,readi:[1,8,44],readm:[8,41],real:1,realiti:4,realli:1,reason:[3,4,26,27],receiv:[1,3,10,26,27],recent:[2,29,45],recogn:[3,15,23,41],recommend:[2,21,29,38,45],reconsid:4,record:[3,41,45],recov:41,recurs:[12,29],recv:1,red:1,redirect:24,reduc:[12,14,44],refactor:41,refer:[2,10,12,15,16,21,29,45],referenc:[5,29,36],reflect:24,refresh:41,regardless:[3,44],regist:1,regular:[3,12,14],reinvent:4,rel:6,relat:[2,10,12,43,44],relationship:[4,5,23,29,41],releas:[2,10,17,26,27,28,29,38,39,45],relev:[21,29,41],reli:4,reliabl:[3,4,44],reload:[23,32,44],remain:[10,41,44,45],rememb:[4,8,23,44,45],remind:4,remov:[2,23,41],renam:41,repeat:1,replac:[2,3,24,33,39,41],repli:4,repo:8,report:5,repositori:44,repr:[26,27,28,29],repres:[10,21,22,29,36,45],represent:41,reproduc:8,req:8,requeijo:41,request:[4,5,10,23,38,39,44],requir:[1,2,3,4,8,14,21,23,24,29,41,44,45],requirements_dev:8,reserv:3,reset:[3,41],reset_loc:41,reskov:41,resourc:[1,2,4],respond:4,respons:[1,12,29,38,39],rest:[11,23,36,38,44,45],restart:44,restor:3,restrict:21,result:[1,2,3,5,12,21,22,24,26,27,29,33,41,45],result_processor:[2,26,27],resultproxi:26,resum:[1,4,21],retri:44,retriev:[2,12,23,42,44],retry_interv:44,retry_limit:44,return_model:[2,21,23,28,29],reus:[0,4,12,15,29,33,38,41],reusabl:[0,29],revamp:41,reveal:3,revers:[2,14,29],revert:[2,41],review:[3,41,44,45],revis:[5,11,44],rewritten:[14,41],rewrot:41,ricardo:43,rich:[12,41],right:[0,3,44],risk:[2,3,14,45],riski:3,roald:41,role:8,roll:[3,15,29,36],rollback:[3,4,15,26,27,28,29,36,41],roman:41,room:45,root:[4,29,44],rootdir:44,roughli:44,rout:38,router:44,row:[2,3,7,10,12,14,23,26,27,28,29,33,41,45],rowproxi:[2,14,33,41],rsa:8,rst:8,rule:[2,14,15,29,33],run:[1,2,3,4,5,6,7,8,11,12,29,33,38,39,44,45],run_sync:3,run_until_complet:45,runtim:[7,44],sa_conn:29,sacrific:4,safe:[1,14,29],safe_connect:3,sai:[1,3,4,38,44,45],said:[1,4],same:[1,2,3,4,5,6,7,11,12,14,15,21,23,24,29,33,38,39,41,44,45],sampl:[3,6,44],sanic:[13,17,37,41,43],sanicframework:43,saniti:3,save:[1,2,29,32,44],savepoint:[15,36],scalabl:4,scalar:[2,3,4,7,10,14,21,23,28,29,41,45],scale:1,scenario:[1,2,4,7,12,14,45],scene:[2,3,7,44],schedul:1,schema:[5,6,17,18,19,21,24,26,27,29,43,44,45],schema_ext:21,schema_for_object:29,schema_visitor:21,schemadropp:34,schemagener:34,schemaitem:[21,41],scope:[4,8,38],scott:3,search:1,sec:1,second:[1,2,3,4,12,23,29],secret:44,section:[8,16],secur:[10,44],see:[1,2,3,6,7,8,10,14,15,19,29,44,45],seek:4,seem:[1,14],seen:[3,7],select:[2,3,4,7,10,11,12,14,15,21,23,26,29,33,41,43,45],select_from:[10,12,33],self:[5,10,11,21,23,26,27,29,33,38],send:[3,4,8,27],sens:4,sent:21,sep:12,separ:[4,8,12,15,41,44],sequenc:[2,26,27,34],sequence_nam:27,sequenti:1,sergei:41,seri:[2,29],serializ:3,serv:4,server:[2,4,8,10,29,38,39,41,42,45],server_default:[10,11,12],server_public_kei:26,server_set:27,servic:[43,44],session:[3,4,44],sessionmak:4,set:[2,3,5,7,8,10,12,14,21,22,23,24,26,27,29,33,38,39,41,44,45],set_bind:[2,7,10,21,22,29,41,45],set_except:10,set_isol:26,set_isolation_level:[3,26,27],set_main_opt:44,set_result:10,setattr:[12,33,41],setter:[3,10,12,21],settl:38,setup:[6,8,27,39],sever:[1,2,21,23,29,45],shadow:22,shall:[15,23,38,44],shallow:3,share:[1,2,7,29,38,39,41],sharp:1,shini:44,shortcut:[2,4,12,15,19,21,22,23,29,33,41,44,45],shortest:4,should:[1,2,3,4,8,12,13,21,23,24,26,27,29,31,39,41,44,45],shouldn:[4,41],show:[3,12,44],shown:[2,36],shtrikker:41,shut:44,shutdown:44,side:[2,4,12,29],sign:1,signific:3,silenc:1,simeon:41,similar:[1,2,3,6,7,8,12,14,15,21,23,41,44,45],similarli:[2,12,14,15,23,29,41],simpl:[1,2,4,6,10,14,21,41,42,43,45],simpler:[1,2,45],simplest:33,simpli:[1,2,3,4,10,11,12,21,23,29,33,38,39,44,45],simplic:1,simplif:3,simplifi:[7,44],simul:[2,3,10],sinc:[1,23,41],singl:[1,2,3,4,12,14,23,26,27,29,45],singular:45,situat:[4,29,36],size:[1,44],skip:[15,36,44],sleep:[1,2,4],slice:1,slower:[4,45],small:[1,2],smaller:4,smarter:4,soft:3,softwar:[3,16,43],sole:[26,27],solut:[0,4,31,45],solv:[1,3,4,16],some:[1,2,3,4,6,7,8,10,11,12,14,23,29,39,41,44,45],someth:[1,2,4,12,44],sometim:[2,3,4,38,45],soon:38,sourc:[16,23,29,41,43,44],speak:[2,3,45],special:[12,26,27,38],specif:[2,16,23],specifi:[2,11,12,14,15,23,24,26,27,29,33,39,41,45],split:[1,45],sql:[2,3,4,5,11,12,14,21,22,23,26,27,29,34,41,43,45],sql_mode:26,sqlalchemi:[0,2,4,5,6,7,11,12,14,16,19,21,22,23,24,26,27,29,33,34,35,39,41,43,44,45],sqltype:[26,27],src:[41,43,44],ssl:[5,8,26,27,39,41,44],ssl_cert_fil:8,ssl_key_fil:8,stabil:10,stabl:[3,41,43,45],stack:[2,29,41,44,45],standard:[2,3,4],stare:44,starleet:41,starlett:[10,17,31,37,41,43,44],start:[1,2,3,4,5,7,10,15,16,23,29,36,38,41,42,45],startup:44,starv:0,starvat:4,state:[1,4,45],stateless:[4,10],statement:[2,3,4,5,10,14,15,19,22,23,26,27,28,41,45],statement_cache_s:27,statement_compil:[26,27],statu:[2,3,7,14,15,21,23,28,29,41,45],status_cod:44,stave:4,step:[1,2,3,4,7,8,16,44],stereotyp:4,stick:1,still:[1,2,3,4,10,12,14,22,24,29,33,36,41,44,45],stop:[4,15,38],storag:[24,41],store:[1,2,3,11,12,24,26,44],stori:[0,3],storm:[3,41],str:[4,11,22,33,44],straightforward:4,strang:45,strategi:[2,17,18,19,33],string:[2,7,10,11,12,14,21,22,23,24,26,27,29,38,41,43,45],stringproperti:[11,32],strongli:4,structur:[3,6,12,23,29],stub:43,stuff:[3,45],style:[4,12,14,41],sub:[4,10,24,33,41,44],subclass:[2,14,21,24,33,36,41,45],subj:8,subload:12,submit:[5,44],submodul:[17,18],subpackag:[17,18],subqueri:[23,41],subsequ:3,subset:8,succeed:29,success:[3,6],successfulli:[3,36,45],suffici:3,suffix:7,sugar:4,suggest:[1,45],suit:[23,41],summari:4,support:[2,3,5,8,11,12,16,17,20,21,23,26,29,33,37,41,43,44,45],support_prepar:[26,28],support_return:[26,28],supports_native_decim:[26,27],suppos:[2,7,24,33,36],sure:[1,3,4,8,12,29,38,44],surpris:3,svx:8,swagger:44,sweet:1,symbol:21,sync:[3,10],sync_engin:3,sync_safe_connect:3,synchron:[1,21],syntax:8,sys:31,system:[1,2,8,10,12,44],tabl:[5,6,7,12,14,15,21,23,24,26,27,34,41,44,45],table_nam:[24,26,27],tableclaus:14,tag:8,take:[1,2,4,7,10,13,14,23,29,33],taken:[1,2,29,38],talk:4,target:[44,45],target_metadata:[6,10,44],task:[1,2,4,17,29,39],tast:[14,44],team:[1,23,41],team_id:23,technic:23,telegram:43,tell:[2,3,45],temporarili:3,ten:[1,4],termin:[8,45],test:[3,8,41,42],test_aiohttp:8,test_crud:44,test_gino:8,test_us:44,testclient:44,text:[3,8,10,11,12,14,21,33,41],textual:[2,12],than:[1,2,3,4,7,10,12,13,15,23,24,29,43,45],thank:[1,2,41],thei:[1,2,3,4,7,8,10,12,14,15,23,24,29,41,44,45],them:[1,3,4,6,7,10,11,12,23,41,44,45],themselv:[1,7],theoret:[4,41],therefor:[1,2,4,7,10,14,21,23,29,38,45],thi:[1,2,3,4,6,7,8,9,10,11,12,14,15,20,21,22,23,24,26,27,29,31,33,35,36,38,39,40,41,44,45],thing:[1,2,3,4,6,7,14,24,41],think:[1,3,4,10],third:[12,14],those:[4,29],though:[1,3,4,14,23,38,45],thought:[3,44],thousand:[1,4],thread:[1,2,3,4],three:2,through:[2,5,8,12,15,21,31,41,44,45],throughput:[1,4],thu:[1,2,4,14,15,29,41],tiago:41,tiangolo:43,tiger:3,tim:43,time:[1,2,3,4,6,10,11,12,15,19,21,23,26,29,38,44],timeout:[7,21,23,26,27,28,29,41],timeouterror:29,timestamp:11,timezon:24,tini:4,tip:5,titl:[43,44],to_dict:[23,41,44],togeth:[1,2,3,29,36,44,45],token:4,toml:44,toni:[41,43],too:[1,2,3,4,10,14,15,29,44,45],took:3,tool:[4,6,43,44,45],toolkit:6,top:[2,3,4,10,14,16,29,44,45],tornado:[17,37,41,43],tortois:43,total:[1,4],touch:[15,36],touchabl:2,tox:8,track:[44,45],trackedmixin:24,tradit:[10,14,45],transact:[2,3,4,5,10,12,17,18,19,21,26,27,28,29,38,43,44],transaction_isol:3,transform:12,transit:3,translat:[2,11,12],trap:[15,36],travers:2,traverse_singl:34,treat:[2,3,7,12,24,29,35],tree:12,tri:[1,4,29,41,45],trigger:[1,4,24],trio:10,troubleshoot:8,truncat:45,tupl:[2,10,12,23,29,33],tupleload:[10,12,33,41],turn:[1,2,3,12,29,38,41],tutori:[14,16,43,44,45],twice:[2,5,26,27,45],twist:[4,43],two:[1,2,4,7,10,12,14,15,23,29,36,44,45],tx1:[15,36],tx2:[15,36],tx3:36,txt:8,type:[2,5,10,11,12,14,23,24,26,29,33,36,41,45],type_nam:27,typic:[4,10,26],ua1:12,ua2:12,ubuntu:43,uid:[7,12,44],ultim:4,ultra:43,unbind:21,unchang:45,under:[2,3,10,12,14,21,23,24,33,41,44,45],underli:[2,3,14,15,29,36,41],unfortun:[3,4],unicod:[6,10,12,14,24,26,27,38,44,45],unifi:[2,41],uninitializederror:[10,30,41],uniqu:[2,12,45],unique_constraint:24,unique_id:24,uniqueconstraint:24,unix:43,unix_socket:26,unknown:[12,41],unknownjsonpropertyerror:30,unless:[2,4,23,45],unlik:1,unnam:[41,44],unnecessarili:38,unpin:41,unpredict:[1,4,38],unrecogn:39,unreli:4,unreus:2,unset:2,unspecifi:23,untest:2,until:[1,10,11,29],untouch:45,unus:[2,4],unwant:14,unwrap:[26,27],updat:[2,3,5,8,11,23,24,29,33,36,41,42,43,44],update_execution_opt:[29,41],updaterequest:[23,45],upgrad:[2,3,6,10,41,44],upon:[3,15,26,27,36],upstream:[3,10],urh:1,url:[2,6,21,26,27,28,35,39,41,44,45],usabl:[2,29,41],usag:[2,5,6,23,29,39,41],use:[1,2,3,4,5,6,8,11,12,13,14,15,21,22,23,26,27,29,31,33,36,38,39,41,43,44,45],use_connection_for_request:[39,44],use_unicod:26,used:[1,2,3,7,10,12,13,14,21,22,23,24,26,27,29,33,41,44,45],useful:[2,4,7,14,23,29,33,36],user1:23,user2:23,user:[2,3,4,5,6,7,8,11,12,13,14,21,23,24,26,27,29,33,36,38,39,43,44,45],user_gett:7,user_id:[10,12,14,23,38],user_queri:7,user_t:7,usermodel:44,usernam:[6,44],users_t:2,uses:[3,10,12,23,35,44],using:[1,2,3,4,7,8,10,12,14,15,23,24,26,27,29,33,41,44,45],usual:[1,2,3,4,7,10,11,12,14,21,23,24,29,44,45],utc:12,util:[3,24,31],uuid4:44,uuid:44,uvicorn:[43,44],uvicornwork:44,uvloop:[1,43],v7oze:29,val:[10,11,32],valid:[3,14],valu:[2,3,7,10,12,14,15,21,23,24,26,27,29,32,33,38,41,44,45],valueload:33,van:41,vanilla:[2,14],vargovcik:41,vari:44,variabl:[6,43,44,45],variant:2,venv:44,veri:[1,2,3,4,11,12,14,23,26,27,29,36,38],verifi:3,version:[3,6,7,8,10,19,20,21,22,23,24,39,41,44],view:[26,44],virtual:[3,8],virtualenv:44,virtualenvwrapp:8,visit:[10,12,21],visit_foreign_key_constraint:34,visit_index:34,visit_metadata:34,visit_sequ:34,visit_t:34,visual:43,vladimir:41,volkova:41,volunt:8,wai:[2,3,4,8,10,11,12,14,15,21,29,44,45],wait:[1,3,4,11,15,23,29,44],wang:[41,43],wanna:[1,4],want:[1,2,3,4,5,6,8,14,21,23,29,38,44,45],ware:10,warehous:22,warn:[41,44],wast:[1,2,4],watch:[1,43],weakref:41,web:[1,7,8,10,41,43],websit:8,weird:3,welcom:[8,14,41,43],well:[1,2,3,4,24],were:[1,4],what:[1,2,3,4,5,14,15,21,44],whatev:[2,4,12,23,29],wheel:4,when:[0,1,2,3,6,7,8,10,12,14,15,19,20,21,22,23,24,26,29,33,36,38,41,44,45],whenev:44,where:[2,3,4,7,10,11,12,14,21,23,29,33,36,44,45],wherea:1,whether:[8,29,36,41],which:[1,2,3,4,7,10,12,14,21,22,23,24,26,27,29,36,38,41,44,45],whichev:41,whoever:8,whole:[1,41,45],whose:[3,14,36,45],why:[0,1,12,45],wide:[3,26,27],wider:45,wiki:43,wikipedia:43,wip:[9,38,40],wire:3,wise:[3,4],wish:[2,8,12,29],with_bind:[2,7,10,12,14,21,22,41],with_tabl:[7,24,41],within:[1,3,4,15,26,27,29,38,41],without:[1,2,3,4,7,11,14,15,21,29,41],won:[1,2,3,4,7,10,14,15,22,36,41,44,45],wonder:1,word:[3,45],work:[1,2,3,4,5,6,8,12,14,17,23,24,26,29,37,41,44,45],workaround:[3,10],workdir:44,worker:44,world:[1,3,14,38],worri:[2,4,10,15,41],worth:[2,14],would:[1,3,4,8,10,12,21,23,33],wrap:[3,10,24],wrapper:[2,3,4,10,24,29,43],write:[1,2,4,5,10,12,42,45],written:[14,43],wrong:[1,4,41],wrote:[1,4],ww4ronfhiqi:43,www:43,wysiwyg:3,x509:8,xss:44,xxx:[23,43],xxxx:5,yai:[1,10],yeah:3,year:3,yellow:1,yes:[1,3],yet:[1,10,11,29],yield:[1,4,14,23,24,29,33,44],yml:44,you:[1,2,3,4,6,7,8,10,11,12,14,15,21,22,23,24,29,36,38,39,41,44,45],your:[1,2,3,4,6,8,10,12,14,15,21,29,41,44,45],your_name_her:8,yourdbnam:44,youtub:43,yurii:41,zen:43,zenof:43,zero:[23,29],zone:[11,12]},titles:["Explanation","Asynchronous Programming 101","Engine and Connection","SQLAlchemy 2.0","Why Asynchronous ORM?","How-to Guides","Use Alembic","Bake Queries","Contributing","CRUD","Frequently Asked Questions","JSON Property","Loaders and Relationship","Connection Pool","Schema Declaration","Transaction","Welcome to GINO\u2019s documentation!","Reference","API Reference","gino package","gino.aiocontextvars module","gino.api module","gino.bakery module","gino.crud module","gino.declarative module","gino.dialects package","gino.dialects.aiomysql module","gino.dialects.asyncpg module","gino.dialects.base module","gino.engine module","gino.exceptions module","gino.ext package","gino.json_support module","gino.loader module","gino.schema module","gino.strategies module","gino.transaction module","Extensions","Sanic Support","Starlette Support","Tornado Support","History","Tutorials","\u5b98\u5ba3\uff1aPython \u5f02\u6b65\u7f16\u7a0b\u518d\u6dfb\u4e00\u5229\u5668","Build a FastAPI Server","GINO Basics"],titleterms:{"101":1,"2017":41,"2018":41,"2019":41,"2020":41,"\u4f18\u52bf\u4e0e\u4e0d\u8db3":43,"\u5148\u8bf4":43,"\u5173\u4e8e\u4f5c\u8005":43,"\u518d\u8bf4":43,"\u53c2\u8003\u6587\u732e":43,"\u5b98\u5ba3":43,"\u5efa\u8bbe\u793e\u4f1a\u4e3b\u4e49":43,"\u5f02\u6b65\u7f16\u7a0b\u518d\u6dfb\u4e00\u5229\u5668":43,"\u65b9\u4fbf\u5feb\u6377":43,"\u662f\u8c01":43,"\u7b80\u5355\u660e\u4e86":43,"new":44,One:12,The:[1,3],Use:[6,7],Useful:16,access:4,add:44,admin:10,advanc:12,aiocontextvar:[10,20],aiomysql:26,alemb:[6,10,44],api:[3,7,18,21,41,44],appli:6,ask:10,async:3,asynchron:[1,4],asyncio:[4,10],asyncpg:27,auto:3,autocommit:3,avail:7,bake:7,bakedqueri:7,bakeri:[7,22],bare:7,base:28,basic:[15,45],batch:10,bug:8,build:44,bulk:10,can:10,column:10,commit:3,complex:10,complic:3,con:1,configur:39,connect:[2,10,13,39,45],content:[19,25,31],contextvar:41,contribut:8,control:15,cooper:1,core:14,creat:[2,6,11,44,45],crud:[9,23,45],current_connect:2,custom:7,databas:[4,10],declar:[14,24,45],defin:10,delet:45,depend:44,develop:41,dialect:[25,26,27,28],differ:10,django:10,document:[8,16],doe:10,don:[4,7],done:4,earli:41,engin:[2,7,10,14,29,41],except:30,execut:[2,10],exist:10,explan:0,explicit:4,express:12,ext:31,extens:[37,44],fastapi:44,featur:[8,10],feedback:8,first:6,fix:8,fly:10,frequent:10,get:[8,45],gino:[7,10,14,16,19,20,21,22,23,24,25,26,27,28,29,30,31,32,33,34,35,36,41,43,44,45],ginoconnect:41,guid:5,guidelin:8,help:4,histori:41,hook:11,how:[4,5,7,10],implement:8,implicit:2,index:[10,11],initi:10,insert:10,instal:45,integr:[7,44],interfac:10,introduct:45,isol:3,join:10,json:11,json_support:32,lazi:[2,39],level:3,link:16,load:10,loader:[7,12,33],local:41,manag:2,mani:12,manual:15,migrat:[6,41],model:[12,44,45],modul:[19,20,21,22,23,24,25,26,27,28,29,30,31,32,33,34,35,36],multipl:10,multitask:1,nest:15,none_as_non:41,note:44,oper:45,orm:[4,10,14],other:12,packag:[19,25,31],paramet:10,pend:41,pool:13,prepar:7,print:10,pro:1,product:[4,44],program:1,project:44,properti:11,pull:8,python:43,queri:[2,7,10,41],question:10,quick:11,raw:10,refer:[17,18],referenc:12,relationship:[10,12],releas:41,report:8,request:8,result:10,retriev:45,reus:2,reusabl:2,revis:6,right:4,run:10,same:10,sanic:38,schema:[14,34],self:12,server:44,set:6,simpl:44,solut:3,sql:10,sqlalchemi:[3,10],ssl:10,starlett:39,start:[8,11,44],starv:4,statement:7,stori:1,strategi:35,submit:8,submodul:[19,25],subpackag:19,support:[10,38,39,40],tabl:10,task:41,test:44,through:10,tip:8,tornado:40,transact:[15,36,41],tutori:42,twice:10,type:8,updat:[10,45],usag:[12,15],use:10,user:10,want:7,welcom:16,what:[7,10],when:4,why:4,work:[10,38,39],write:[8,44],xxxx:10}}) \ No newline at end of file diff --git a/docs/en/1.1b2/tutorials.html b/docs/en/1.1b2/tutorials.html new file mode 100644 index 0000000..1771be3 --- /dev/null +++ b/docs/en/1.1b2/tutorials.html @@ -0,0 +1,235 @@ + + + + + + + + Tutorials - GINO 1.1.0b2 documentation + + + + + + + + + + + +

+ +

+ + + + + +

+ + + +

+ + HOME + + + CREDITS + + +

Tutorials

How-to Guides

Explanation

Reference

+ +

Tutorials¶

+ +

+ + +

+ + + +
+ This work is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License. +

+ +

Tutorials

+ + +

+ Add your language here. +

+ +

+ +

+ + + + + + + + + + + \ No newline at end of file diff --git a/docs/en/1.1b2/tutorials/announcement.html b/docs/en/1.1b2/tutorials/announcement.html new file mode 100644 index 0000000..4a75d3f --- /dev/null +++ b/docs/en/1.1b2/tutorials/announcement.html @@ -0,0 +1,491 @@ + + + + + + + + 官宣：Python 异步编程再添一利器 - GINO 1.1.0b2 documentation + + + + + + + + + + + +

+ + +

Tutorials

How-to Guides

Explanation

Reference

+ +

官宣：Python 异步编程再添一利器¶

+
GINO 填补了国内外 asyncio ORM 领域的空白
+

GINO 是谁¶

传统 ORM 的学习曲线前平后陡，能在快速原型开发中大展身手，但应用到大型项目中却十分考验开发人员的平均水平。

所以在 2017 年创作之初，我就给 GINO 定下了两个业绩目标：1) 方便快捷，2) 简单明了。三年后的今天，我索性在 1.0 稳定版发布的前夕做个年终总结。

先说“方便快捷”¶

+
“方便快捷”主要说的是开发效率。
+

from gino import Gino
+db = Gino()
+class User(db.Model):
+    __tablename__ = "users"
+    id = db.Column(db.Integer, primary_key=True)
+    name = db.Column(db.String)
+

+

这么定义表结构甚至让人有点小兴奋。咦，为什么这么眼熟？

是不是十分方便、十分快捷？不止这样。

daisy = await User.create(name="daisy")
+await daisy.update(name="Daisy").apply()
+

+

为了让不同应用场景下的用户体验到最大的善意，GINO 目前支持三种不同程度的用法，成功实现了对同期竞品 +asyncpgsa21 的降维打击：

最少侵入型22：SQLAlchemy core 原教旨主义者，只有异步执行时才用到 GINO。
终身不婚型23：天生厌恶“对象”，只愿定义“表”，空手接 SQL。
火力全开型24：最大程度的便利，非典型异步 ORM。

再说“简单明了”¶

+
Explicit is better than implicit.
+
Simple is better than complex.
+
–The Zen of Python, PEP 2027
+

Python 之禅完美表达了 GINO 的立场——明确性（explicitness）对于上了规模的异步工程项目来说尤为重要，因此 GINO 的很多设计都受到了明确性的影响。

等到需要操作数据库的时候，你一定会有感知的。比如执行 INSERT 要用 +u = await User.create()，而 UPDATE 则是 +await u.update(name="Daisy").apply()。

Hint

这里的 await 就是明确性的关键，意味着我们要跳出去执行数据库操作了。换句话说，没有 await +就没有数据库操作。

class Book(db.Model):
+    __tablename__ = "books"
+    id = db.Column(db.Integer, primary_key=True)
+    title = db.Column(db.String)
+    author_id = db.ForeignKey("users.id")
+

+

然后这样来加载这种多对一关系，以同时获取所有的书和他们的作者：

query = Book.outerjoin(User).select()
+loader = Book.load(author=User)
+async for book in query.gino.load(loader).iterate():
+    print(book.title, "written by", book.author.name)
+

+

很简单的一个外连接查询 Book.outerjoin(User)，配合一个直观的加载器 +Book.load(author=User)，就实现了：

执行 SELECT * FROM books LEFT JOIN users ON ...；
将数据库返回结果的每一行中，属于 books 的字段加载成一个 Book 实例；
然后将该行中剩下的属于 users 的字段加载成一个 User 实例；
最后将 User 实例设置到 Book 实例的 author 属性上。

优势与不足¶

以下是近来统计到的关于 GINO 的应用案例：

笔者工作上开发的一个服务：https://github.com/uc-cdis/metadata-service
还是笔者自己写的一个工具：https://github.com/fantix/aintq
一个汇率 API 服务：https://exchangeratesapi.io/
+ +
各种 Telegram、Discord 的 Bot。
ArchLinux 用户包：https://aur.archlinux.org/packages/python-gino/
+ +
https://github.com/bryanforbes/gino-stubs/
俄语教程：https://www.youtube.com/watch?v=WW4rOnfhiQY
高性能模板项目：https://github.com/leosussan/fastapi-gino-arq-uvicorn
还有几个商用的，但没征得同意就不贴出来了。

另外，GINO 还贴心地提供了中文文档32，从上手教程到原理说明应有尽有（虽然文档还在努力编写中！）：

建设社会主义¶

GINO 是一个开源项目，所以欢迎大家一起来建设！长期活跃的贡献者还能获赠价值 4888 元的 PyCharm +专业版全家桶 License 一枚33（没有发票）。

目前急需帮助的有：

各个 Web 框架插件的维护工作需要多人认领；
更多的例子和文档，以及中文、俄文的翻译；
MySQL 的支持。

以及下面这些一直需要的帮助：

用 GINO，找 bug，提建议；
修 bug，做功能，提 PR；
维护社区，回答问题，参与讨论；
最后也是最重要的：去 GitHub 上给 GINO 加一颗星星！

关于作者¶

特别感谢 Tony Wang 对 GINO 项目的贡献，以及所有人的贡献。

参考文献¶

1(1,2): Facebook. Tornado. https://zh.wikipedia.org/wiki/Tornado.
+
2: Python Software Foundation. asyncio — 异步 I/O. +https://docs.python.org/zh-cn/3/library/asyncio.html.
+
3: 维基百科. GNU. https://zh.wikipedia.org/wiki/GNU.
+
4: 维基百科. 对象关系映射. +https://zh.wikipedia.org/wiki/对象关系映射.
+
5: 维基百科. SQLAlchemy. https://zh.wikipedia.org/wiki/SQLAlchemy.
+
6: Michael Bayer. SQLAlchemy Core - SQLAlchemy. Documentation. +https://docs.sqlalchemy.org/en/13/core/index.html.
+
7: Michael Bayer. Welcome to Alembic’s documentation!. +https://alembic.sqlalchemy.org/en/latest/.
+
8: Hong Minhee. A curatedlist of awesome tools for SQLAlchemy. +https://github.com/dahlia/awesome-sqlalchemy.
+
9: Ricardo GarciaSilva. Does it have postgis support?. +https://github.com/python-gino/gino/issues/627.
+
10: Fantix King. GINO 基础教程 - 增删改查. +https://python-gino.org/docs/zh/master/tutorials/tutorial.html#crud-operations.
+
11: Python Software Foundation. contextvars —Context Variables. +https://docs.python.org/3/library/contextvars.html.
+
12: Fantix King. gino/aiocontextvars.py. +https://github.com/python-gino/gino/blob/f2c273a43a3ed893a767d4239046f2befabf510d/src/gino/aiocontextvars.py.
+
13: Fantix King. 数据库事务. +https://python-gino.org/docs/zh/master/how-to/transaction.html.
+
14: Fantix King. 引擎与连接. +https://python-gino.org/docs/zh/master/explanation/engine.html.
+
15: GINO Community. GINO Community. https://github.com/python-gino/.
+
16: aiohttp maintainers. Welcome to AIOHTTP. https://docs.aiohttp.org/en/stable/.
+
17: Sanic Community. SanicFramework. https://sanicframework.org/.
+
18: Sebastián Ramírez. FastAPI. https://fastapi.tiangolo.com/.
+
19: Encode OSS. Starlette. https://www.starlette.io/.
+
20: Philip Jones. Quart Documentation. https://pgjones.gitlab.io/quart/.
+
21: Canopy. asyncpgsa - A wrapper around asyncpg for use with sqlalchemy. +https://github.com/CanopyTax/asyncpgsa.
+
22: Fantix King. 表结构定义 -GINO 引擎. +https://pythongino.org/docs/zh/master/how-to/schema.html#gino-engine.
+
23: Fantix King. 表结构定义 - GINO core. +https://python-gino.org/docs/zh/master/how-to/schema.html#gino-core.
+
24: Fantix King. 表结构定义 - GINO ORM. +https://python-gino.org/docs/zh/master/how-to/schema.html#gino-orm.
+
25: MagicStack Inc. +asyncpg - A fast PostgreSQL Database Client Library for Python/asyncio. +https://github.com/MagicStack/asyncpg.
+
26: MagicStack Inc. uvloop -Ultra fast asyncio event loop. +https://github.com/MagicStack/uvloop.
+
27: Tim Peters. PEP ‒ The Zenof Python. https://www.python.org/dev/peps/pep-0020/.
+
28: Wikipedia. Plain old Java object. +https://en.wikipedia.org/wiki/Plain_old_Java_object.
+
29: Fantix King. 加载器与关系. +https://python-gino.org/docs/zh/master/how-to/loaders.html.
+
30: Andrey Bondar. Tortoise ORM. https://tortoise.github.io/.
+
31: Encode OSS. ORM - An async ORM. https://github.com/encode/orm.
+
32: Fantix King. 欢迎来到 GINO 的文档！. +https://python-gino.org/docs/zh/master/index.html.
+
33: JetBrains s.r.o. Open Source Licenses. +https://www.jetbrains.com/community/opensource/#support.
+

+ + +

+ + + +
+ This work is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License. +

+ +

官宣：Python 异步编程再添一利器
- GINO 是谁
- 先说“方便快捷”
- 再说“简单明了”
- 优势与不足
- 建设社会主义
- 关于作者
- 参考文献
+

+ + +

+ +

+ + +

+ Add your language here. +

+ +

+ +

+ + + + + + + + + + + \ No newline at end of file diff --git a/docs/en/1.1b2/tutorials/fastapi.html b/docs/en/1.1b2/tutorials/fastapi.html new file mode 100644 index 0000000..9a320ff --- /dev/null +++ b/docs/en/1.1b2/tutorials/fastapi.html @@ -0,0 +1,737 @@ + + + + + + + + Build a FastAPI Server - GINO 1.1.0b2 documentation + + + + + + + + + + + +

+ + +

Tutorials

How-to Guides

Explanation

Reference

+ +

Build a FastAPI Server¶

In this tutorial, we’ll build a production-ready FastAPI server together. +The full functional example is available here.

Our application stack will look like this:

Start a New Project¶

Instead of pip, let’s use the shiny Poetry to manage our project. Follow the link to +install Poetry, and create our new +project in an empty directory:

$ mkdir gino-fastapi-demo
+$ cd gino-fastapi-demo
+$ git init
+$ poetry init
+

+

Add Dependencies¶

FastAPI is built on top of the Starlette framework, so we shall use the GINO +extension for Starlette. Simply run:

$ poetry add gino[starlette]
+

+

Then let’s add FastAPI, together with the lightning-fast ASGI server Uvicorn, and +Gunicorn as a production application server:

$ poetry add fastapi uvicorn gunicorn
+

+

For database migration, we’ll use Alembic. Because it uses normal DB-API, we need +psycopg here too:

$ poetry add alembic psycopg2
+

+

At last, let’s add pytest in the development environment for testing. We also want to +add the requests library to use the Starlette TestClient:

$ poetry add -D pytest requests
+

+

Hint

That’s all, this is my pyproject.toml created by Poetry, yours should look similar:

[tool.poetry]
+name = "gino-fastapi-demo"
+version = "0.1.0"
+description = ""
+authors = ["Fantix King <fantix.king@gmail.com>"]
+
+[tool.poetry.dependencies]
+python = "^3.8"
+gino = {version = "^1.0", extras = ["starlette"]}
+fastapi = "^0.54.1"
+uvicorn = "^0.11.3"
+gunicorn = "^20.0.4"
+alembic = "^1.4.2"
+psycopg2 = "^2.8.5"
+
+[tool.poetry.dev-dependencies]
+pytest = "^5.4.1"
+requests = "^2.23.0"
+
+[build-system]
+requires = ["poetry>=0.12"]
+build-backend = "poetry.masonry.api"
+

+

$ git add pyproject.toml poetry.lock
+$ git commit -m 'add project dependencies'
+

+

Write a Simple Server¶

Now let’s write some Python code.

We’ll create an extra src directory to include all the Python files, as demonstrated +in the diagram below. This is known as the “src layout” providing a cleaner hierarchy.

The root Python package of our project is named as gino_fastapi_demo, under which we +will create two Python modules:

asgi as the ASGI entry point - we’ll feed it to the ASGI server
main to initialize our server

Here’s main.py:

from fastapi import FastAPI
+
+def get_app():
+    app = FastAPI(title="GINO FastAPI Demo")
+    return app
+

+

And we’ll simply instantiate our application in asgi.py:

from .main import get_app
+
+app = get_app()
+

+

Then run poetry install to link our Python package into the PYTHONPATH in +development mode. We’ll be able to start a Uvicorn development server after that:

$ poetry install
+Installing dependencies from lock file
+
+No dependencies to install or update
+
+  - Installing gino-fastapi-demo (0.1.0)
+
+$ poetry run uvicorn gino_fastapi_demo.asgi:app --reload
+INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
+INFO:     Started reloader process [53010]
+INFO:     Started server process [53015]
+INFO:     Waiting for application startup.
+INFO:     Application startup complete.
+

+

Hint

As mentioned previously, if you’re in your own virtualenv, the command poetry run +uvicorn can be simplified as just uvicorn.

poetry run is a convenient shortcut to run the following command in the +virtualenv managed by Poetry.

Add GINO Extension¶

Now let’s add GINO to our server.

First of all, we need a way to configure the database. In this tutorial, we’ll use the +configuration system from Starlette. +Add src/gino_fastapi_demo/config.py as follows:

from sqlalchemy.engine.url import URL, make_url
+from starlette.config import Config
+from starlette.datastructures import Secret
+
+config = Config(".env")
+
+DB_DRIVER = config("DB_DRIVER", default="postgresql")
+DB_HOST = config("DB_HOST", default=None)
+DB_PORT = config("DB_PORT", cast=int, default=None)
+DB_USER = config("DB_USER", default=None)
+DB_PASSWORD = config("DB_PASSWORD", cast=Secret, default=None)
+DB_DATABASE = config("DB_DATABASE", default=None)
+DB_DSN = config(
+    "DB_DSN",
+    cast=make_url,
+    default=URL(
+        drivername=DB_DRIVER,
+        username=DB_USER,
+        password=DB_PASSWORD,
+        host=DB_HOST,
+        port=DB_PORT,
+        database=DB_DATABASE,
+    ),
+)
+DB_POOL_MIN_SIZE = config("DB_POOL_MIN_SIZE", cast=int, default=1)
+DB_POOL_MAX_SIZE = config("DB_POOL_MAX_SIZE", cast=int, default=16)
+DB_ECHO = config("DB_ECHO", cast=bool, default=False)
+DB_SSL = config("DB_SSL", default=None)
+DB_USE_CONNECTION_FOR_REQUEST = config(
+    "DB_USE_CONNECTION_FOR_REQUEST", cast=bool, default=True
+)
+DB_RETRY_LIMIT = config("DB_RETRY_LIMIT", cast=int, default=1)
+DB_RETRY_INTERVAL = config("DB_RETRY_INTERVAL", cast=int, default=1)
+

+

$ DB_HOST=localhost DB_USER=postgres poetry run uvicorn gino_fastapi_demo.asgi:app --reload
+

+

Or set them in the file .env (this file must not be committed into Git, remember to +add it to .gitignore):

DB_HOST=localhost
+DB_USER=postgres
+

+

Tip

Alternatively, you could also set DB_DSN to for example +postgresql://user:password@localhost:5432/dbname to override the other individual +config values like DB_HOST defined before DB_DSN.

Then, create a new Python sub-package gino_fastapi_demo.models to encapsulate +database-related code, and add the code below to +src/gino_fastapi_demo/models/__init__.py:

from gino.ext.starlette import Gino
+
+from .. import config
+
+db = Gino(
+    dsn=config.DB_DSN,
+    pool_min_size=config.DB_POOL_MIN_SIZE,
+    pool_max_size=config.DB_POOL_MAX_SIZE,
+    echo=config.DB_ECHO,
+    ssl=config.DB_SSL,
+    use_connection_for_request=config.DB_USE_CONNECTION_FOR_REQUEST,
+    retry_limit=config.DB_RETRY_LIMIT,
+    retry_interval=config.DB_RETRY_INTERVAL,
+)
+

+

At last, modify src/gino_fastapi_demo/main.py to install the GINO extension:

 from fastapi import FastAPI
++
++from .models import db
+
+ def get_app():
+     app = FastAPI(title="GINO FastAPI Demo")
++    db.init_app(app)
+     return app
+

+

Saving the file, you should see the Uvicorn server reloads our changes and connects to +the database:

WARNING:  Detected file change in 'src/gino_fastapi_demo/main.py'. Reloading...
+INFO:     Shutting down
+INFO:     Waiting for application shutdown.
+INFO:     Application shutdown complete.
+INFO:     Finished server process [63562]
+INFO:     Started server process [63563]
+INFO:     Waiting for application startup.
+INFO:     Connecting to the database: postgresql://fantix:***@localhost
+INFO:     Database connection pool created: <asyncpg.pool.Pool max=16 min=1 cur=1 use=0>
+INFO:     Application startup complete.
+

+

Create Models and API¶

It’s time to implement the API now. Let’s say we are building a user management service, +through which we could add users, list users and delete users.

First of all, we need a database table users to store the data, mapped to a GINO +model named User. We shall add the model in gino_fastapi_demo.models.users:

from . import db
+
+class User(db.Model):
+    __tablename__ = "users"
+
+    id = db.Column(db.BigInteger(), primary_key=True)
+    nickname = db.Column(db.Unicode(), default="unnamed")
+

+

The model definition is simple enough to explain itself.

from fastapi import APIRouter
+from pydantic import BaseModel
+
+from ..models.users import User
+
+router = APIRouter()
+
+@router.get("/users/{uid}")
+async def get_user(uid: int):
+    user = await User.get_or_404(uid)
+    return user.to_dict()
+
+class UserModel(BaseModel):
+    name: str
+
+@router.post("/users")
+async def add_user(user: UserModel):
+    rv = await User.create(nickname=user.name)
+    return rv.to_dict()
+
+@router.delete("/users/{uid}")
+async def delete_user(uid: int):
+    user = await User.get_or_404(uid)
+    await user.delete()
+    return dict(id=uid)
+
+def init_app(app):
+    app.include_router(router)
+

+

import logging
+from importlib.metadata import entry_points
+
+logger = logging.getLogger(__name__)
+
+def load_modules(app=None):
+    for ep in entry_points()["gino_fastapi_demo.modules"]:
+        logger.info("Loading module: %s", ep.name)
+        mod = ep.load()
+        if app:
+            init_app = getattr(mod, "init_app", None)
+            if init_app:
+                init_app(app)
+

+

Hint

If you’re running Python < 3.8, you’ll need this importlib-metadata backport.

And call it in our application factory:

 def get_app():
+     app = FastAPI(title="GINO FastAPI Demo")
+     db.init_app(app)
++    load_modules(app)
+     return app
+

+

Finally, define the entry points in pyproject.toml following the Poetry document +for plugins:

[tool.poetry.plugins."gino_fastapi_demo.modules"]
+"users" = "gino_fastapi_demo.views.users"
+

+

Run poetry install again to activate the entry points - you may need to restart the +Uvicorn development server manually, as the reloader cannot capture the changes we made +to pyproject.toml.

Now you should be able to see the 3 new APIs on the Swagger UI. But none of them works, +because we still haven’t created the database tables.

Integrate with Alembic¶

To get started with Alembic, run this command in the project root directory:

$ poetry run alembic init migrations
+

+

For Alembic to use our data models defined with GINO (and of course the database +config), we need to modify migrations/env.py to connect with the GINO instance:

 # add your model's MetaData object here
+ # for 'autogenerate' support
+ # from myapp import mymodel
+ # target_metadata = mymodel.Base.metadata
+-target_metadata = None
++from gino_fastapi_demo.config import DB_DSN
++from gino_fastapi_demo.main import db, load_modules
++
++load_modules()
++config.set_main_option("sqlalchemy.url", str(DB_DSN))
++target_metadata = db
+

+

Then create our first migration revision with:

$ poetry run alembic revision --autogenerate -m 'add users table'
+INFO  [alembic.runtime.migration] Context impl PostgresqlImpl.
+INFO  [alembic.runtime.migration] Will assume transactional DDL.
+INFO  [alembic.autogenerate.compare] Detected added table 'users'
+  Generating migrations/versions/32c0feba61ea_add_users_table.py ...  done
+

+

The generated revision file should roughly look like this:

def upgrade():
+    op.create_table(
+        "users",
+        sa.Column("id", sa.BigInteger(), nullable=False),
+        sa.Column("nickname", sa.Unicode(), nullable=True),
+        sa.PrimaryKeyConstraint("id"),
+    )
+
+def downgrade():
+    op.drop_table("users")
+

+

Hint

Eventually, let’s apply this migration, by upgrading to the latest revision:

$ poetry run alembic upgrade head
+INFO  [alembic.runtime.migration] Context impl PostgresqlImpl.
+INFO  [alembic.runtime.migration] Will assume transactional DDL.
+INFO  [alembic.runtime.migration] Running upgrade  -> 32c0feba61ea, add users table
+

+

Now all the APIs should be fully operational, try with the Swagger UI.

Write the Tests¶

In order not to break our development database with running tests, let’s create a +separate database to run tests. Apply this change to gino_fastapi_demo.config:

 config = Config(".env")
+
++TESTING = config("TESTING", cast=bool, default=False)
+
+ DB_DRIVER = config("DB_DRIVER", default="postgresql")
+ DB_HOST = config("DB_HOST", default=None)
+ DB_PORT = config("DB_PORT", cast=int, default=None)
+ DB_USER = config("DB_USER", default=None)
+ DB_PASSWORD = config("DB_PASSWORD", cast=Secret, default=None)
+ DB_DATABASE = config("DB_DATABASE", default=None)
++if TESTING:
++    if DB_DATABASE:
++        DB_DATABASE += "_test"
++    else:
++        DB_DATABASE = "gino_fastapi_demo_test"
+ DB_DSN = config(
+

+

Hint

Then, let’s create our pytest fixture in tests/conftest.py:

import pytest
+from alembic.config import main
+from starlette.config import environ
+from starlette.testclient import TestClient
+
+environ["TESTING"] = "TRUE"
+
+@pytest.fixture
+def client():
+    from gino_fastapi_demo.main import db, get_app
+
+    main(["--raiseerr", "upgrade", "head"])
+
+    with TestClient(get_app()) as client:
+        yield client
+
+    main(["--raiseerr", "downgrade", "base"])
+

+

Here’s a sample test in tests/test_users.py:

import uuid
+
+def test_crud(client):
+    # create
+    nickname = str(uuid.uuid4())
+    r = client.post("/users", json=dict(name=nickname))
+    r.raise_for_status()
+
+    # retrieve
+    url = f"/users/{r.json()['id']}"
+    assert client.get(url).json()["nickname"] == nickname
+
+    # delete
+    client.delete(url).raise_for_status()
+    assert client.get(url).status_code == 404
+

+

Then run the test:

$ poetry run pytest
+=========================== test session starts ===========================
+platform darwin -- Python 3.8.2, pytest-5.4.1, py-1.8.1, pluggy-0.13.1
+rootdir: gino-fastapi-demo
+collected 1 item
+
+tests/test_users.py .                                               [100%]
+
+============================ 1 passed in 1.21s ============================
+

+

Notes for Production¶

Given the popularity of Docker/Kubernetes, we’ll build a Dockerfile for our demo:

FROM python:3.8-alpine as base
+
+FROM base as builder
+RUN apk add --no-cache gcc musl-dev libffi-dev openssl-dev make postgresql-dev
+RUN pip install poetry
+COPY . /src/
+WORKDIR /src
+RUN python -m venv /env && . /env/bin/activate && poetry install
+
+FROM base
+RUN apk add --no-cache postgresql-libs
+COPY --from=builder /env /env
+COPY --from=builder /src /src
+WORKDIR /src
+CMD ["/env/bin/gunicorn", "gino_fastapi_demo.asgi:app", "-b", "0.0.0.0:80", "-k", "uvicorn.workers.UvicornWorker"]
+

+

Let’s review what we have in the project.

This is the end of the tutorial to build a demo. Below is an incomplete checklist to +go live:

Set DB_RETRY_LIMIT to a larger number to allow staring the application server +before the database is fully ready.
Implement the same retry logic in migrations/env.py so that Alembic gets the same +functionality.
Enable DB_SSL if needed.
Write a docker-compose.yml for other developers to get a quick taste or even use +it for development.
Enable CI, install pytest-cov and use --cov-fail-under to guarantee coverage.
Integrate static code analysis tools and security/CVE checking tools.
Automate Alembic upgrade properly - e.g. after new version is deployed.
Be aware of the common security attacks like CSRF, XSS, etc.
Write load tests.

Again, the source code of the demo is available here, +and the source of this tutorial is here. +Please feel free to submit PRs to fix issues or add your thoughts. Happy hacking!

+ + +

+ + + +
+ This work is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License. +

+ +

Build a FastAPI Server
+

+ + +

+ +

+ + +

+ Add your language here. +

+ +

+ +

+ + + + + + + + + + + \ No newline at end of file diff --git a/docs/en/1.1b2/tutorials/tutorial.html b/docs/en/1.1b2/tutorials/tutorial.html new file mode 100644 index 0000000..8dd7590 --- /dev/null +++ b/docs/en/1.1b2/tutorials/tutorial.html @@ -0,0 +1,600 @@ + + + + + + + + GINO Basics - GINO 1.1.0b2 documentation + + + + + + + + + + + +

+ +

+ + + + + + + +

+ + + +

+ + HOME + + + CREDITS + + +

Tutorials

How-to Guides

Explanation

Reference

+ +

GINO Basics¶

This tutorial helps beginners to get started with the basic part of GINO. +Target audiences of this tutorial should have basic knowledge of:

RDBMS, especially PostgreSQL
Asynchronous programming in Python

Knowledge of SQLAlchemy is not required.

Introduction¶

Installation¶

To install GINO, run this command in your terminal:

$ pip install gino
+

+

This is the preferred method to install GINO, as it will always install the +most recent stable release.

If you don’t have pip installed, this Python installation guide can guide +you through the process.

Alternatively, if you are using Poetry to manage your project dependencies, +you may want to run:

$ poetry add gino
+

+

Declare Models¶

First of all, we’ll need a Gino object, usually under the +name of db as a global variable:

from gino import Gino
+
+db = Gino()
+

+

db acts like a reference to the database, most database interactions will +go through it.

class User(db.Model):
+    __tablename__ = 'users'
+
+    id = db.Column(db.Integer(), primary_key=True)
+    nickname = db.Column(db.Unicode(), default='noname')
+

+

Note

If you need constraints or indexes covering multiple columns these are also +defined using properties in model classes. The property names must be unique, +but are otherwise not used. Example:

class Booking(db.Model):
+    __tablename__ = 'bookings'
+
+   day = db.Column(db.Date)
+   booker = db.Column(db.String)
+   room = db.Column(db.String)
+
+   _pk = db.PrimaryKeyConstraint('day', 'booker', name='bookings_pkey')
+   _idx1 = db.Index('bookings_idx_day_room', 'day', 'room', unique=True)
+   _idx2 = db.Index('bookings_idx_booker_room', 'booker', 'room')
+

+

It is also possible to define model constraints and indexes outside the model +class if that is preferred. For more details on constraints and indexes, see +here in the +SQLAlchemy documentation.

Get Connected¶

The declaration only defined the mapping, it does not create the actual table +in the database. To do that, we need to get connected first. Let’s create a +PostgreSQL database for this tutorial:

$ createdb gino
+

+

Then we tell our db object to connect to this database:

import asyncio
+
+async def main():
+    await db.set_bind('postgresql://localhost/gino')
+
+asyncio.get_event_loop().run_until_complete(main())
+

+

Note

Now that we are connected, let’s create the table in database (in the same +main() method):

await db.gino.create_all()
+

+

Warning

In practice create_all() is usually +not an ideal solution. To manage database schema, tool like Alembic is +recommended, please see how to Use Alembic.

If you want to explicitly disconnect from the database, you can do this:

await db.pop_bind().close()
+

+

Let’s review the code we have so far together in one piece before moving on:

import asyncio
+from gino import Gino
+
+db = Gino()
+
+
+class User(db.Model):
+    __tablename__ = 'users'
+
+    id = db.Column(db.Integer(), primary_key=True)
+    nickname = db.Column(db.Unicode(), default='noname')
+
+
+async def main():
+    await db.set_bind('postgresql://localhost/gino')
+    await db.gino.create_all()
+
+    # further code goes here
+
+    await db.pop_bind().close()
+
+
+asyncio.get_event_loop().run_until_complete(main())
+

+

CRUD Operations¶

In order to operate on the database, one of GINO’s core features is to Create, +Retrieve, Update or Delete model objects, also known as the CRUD operations.

Create¶

Let’s start by creating a User:

user = await User.create(nickname='fantix')
+# This will cause GINO to execute this SQL with parameter 'fantix':
+# INSERT INTO users (nickname) VALUES ($1) RETURNING users.id, users.nickname
+

+

As mentioned previously, user object represents the newly created row in +the database. You can get the value of each columns by the declared column +properties on the object:

print(f'ID:       {user.id}')           # 1
+print(f'Nickname: {user.nickname}')     # fantix
+

+

It is also possible to create a model instance in-memory first, modify it, then +finally create it in the database:

user = User(nickname='fantix')
+user.nickname += ' (founder)'
+await user.create()
+

+

Retrieve¶

To retrieve a model object from database by primary key, you can use the class +method get() on the model class. Now let’s retrieve +the same row:

user = await User.get(1)
+# SQL (parameter: 1):
+# SELECT users.id, users.nickname FROM users WHERE users.id = $1
+

+

Normal SQL queries are done through a class property +query. For example, let’s retrieve all User +objects from database as a list:

all_users = await db.all(User.query)
+# SQL:
+# SELECT users.id, users.nickname FROM users
+

+

Alternatively, you can use the gino extension on +query. This has exactly the same effect as above:

all_users = await User.query.gino.all()
+# SQL:
+# SELECT users.id, users.nickname FROM users
+

+

Note

Now let’s add some filters. For example, find all users with ID lower than 10:

founding_users = await User.query.where(User.id < 10).gino.all()
+# SQL (parameter: 10):
+# SELECT users.id, users.nickname FROM users WHERE users.id < $1
+

+

Read more here +about writing queries, because the query object is exactly from SQLAlchemy core.

Warning

Also, GINO keeps no track of model objects, therefore getting the same row +twice returns two different object with identical values. Modifying one +does not magically affect the other one.

Sometimes we want to get only one object, for example getting the user by name +when logging in. There’s a shortcut for this scenario:

user = await User.query.where(User.nickname == 'fantix').gino.first()
+# SQL (parameter: 'fantix'):
+# SELECT users.id, users.nickname FROM users WHERE users.nickname = $1
+

+

If there is no user named “fantix” in database, user will be None.

And sometimes we may want to get a single value from database, getting the name +of user with ID 1 for example. Then we can use the +select() class method:

name = await User.select('nickname').where(User.id == 1).gino.scalar()
+# SQL (parameter: 1):
+# SELECT users.nickname FROM users WHERE users.id = $1
+print(name)  # fantix
+

+

Or get the count of all users:

population = await db.func.count(User.id).gino.scalar()
+# SQL:
+# SELECT count(users.id) AS count_1 FROM users
+print(population)  # 17 for example
+

+

Update¶

Then let’s try to make some modifications. In this example we’ll mixin some +retrieve operations we just tried.

# create a new user
+user = await User.create(nickname='fantix')
+
+# get its name
+name = await User.select('nickname').where(
+    User.id == user.id).gino.scalar()
+assert name == user.nickname  # they are both 'fantix' before the update
+
+# modification here
+await user.update(nickname='daisy').apply()
+# SQL (parameters: 'daisy', 1):
+# UPDATE users SET nickname=$1 WHERE users.id = $2 RETURNING users.nickname
+print(user.nickname)  # daisy
+
+# get its name again
+name = await User.select('nickname').where(
+    User.id == user.id).gino.scalar()
+print(name)  # daisy
+assert name == user.nickname  # they are both 'daisy' after the update
+

+

Note

Tip

update() on model object affects only the row +represented by the object. If you want to do update with wider condition, you +can use the update() on model class level, with a +bit difference:

await User.update.values(nickname='Founding Member ' + User.nickname).where(
+    User.id < 10).gino.status()
+# SQL (parameter: 'Founding Member ', 10):
+# UPDATE users SET nickname=($1 || users.nickname) WHERE users.id < $2
+
+name = await User.select('nickname').where(
+    User.id == 1).gino.scalar()
+print(name)  # Founding Member fantix
+

+

There is no UpdateRequest here, everything is again +SQLAlchemy clause, its +documentation here for +your reference.

Delete¶

At last. Deleting is similar to updating, but way simpler.

user = await User.create(nickname='fantix')
+await user.delete()
+# SQL (parameter: 1):
+# DELETE FROM users WHERE users.id = $1
+print(await User.get(user.id))  # None
+

+

Hint

Remember the model object is in memory? In the last print() +statement, even though the row is already deleted in database, the object +user still exists with its values untouched.

Or mass deletion (never forget the where clause, unless you want to truncate +the whole table!!):

await User.delete.where(User.id > 10).gino.status()
+# SQL (parameter: 10):
+# DELETE FROM users WHERE users.id > $1
+

+

With basic CRUD, you can already make some amazing stuff with +GINO. This tutorial ends here, please find out more in detail from the rest of +this documentation, and have fun hacking!

+ + +

+ + + +
+ This work is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License. +

+ +

GINO Basics
- Introduction
- Installation
- Declare Models
- Get Connected
- CRUD Operations
  - Create
  - Retrieve
  - Update
  - Delete
  +
+

+ + +

+ +

+ + +

+ Add your language here. +

+ +