Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Documentation: proofreading and small fixes #473

Merged
merged 4 commits into from
Aug 10, 2023
Merged

Documentation: proofreading and small fixes #473

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
878817c
Add command line arguments table and cleanup
mejroslav Aug 10, 2023
e14d9e9
Reformat docstrings
mejroslav Aug 10, 2023
c49743d
Fix reference
mejroslav Aug 10, 2023
a19ee14
Fix relicts from rst
mejroslav Aug 10, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 3 additions & 18 deletions asab/application.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -207,22 +207,7 @@ def create_argument_parser(
Create an `argparse.ArgumentParser` object supplemented by default ASAB arguments.

This method can be overridden to adjust argparse configuration.
Refer to the Python standard library to [`argparse.ArgumentParser`](https://docs.python.org/3/library/argparse.html?highlight=argumentparser#argumentparser-objects) for details of arguments.

Default ASAB arguments:

| Argument | Type | Action |
| :----- | :----- | :----- |
| `-c`, `--config` | str | specify a path to a configuration file |
| `-d`, `--daemonize` | bool | run daemonized (in the background) |
| `-k`, `--kill` | bool | kill a running daemon and quit |
| `-l`, `--log-file` | str | specify a path to a log file |
| `-s`, `--syslog`| bool | enable logging to a syslog |
| `-v`, `--verbose` | bool | print more information (enable debug output) |
| `-w`, `--web-api` | str | activate Asab web API (default listening port is 0.0.0.0:8080) |
| `--startup-housekeeping` | | trigger housekeeping event immediately after application startup |


Refer to the Python standard library to [`argparse.ArgumentParser`](https://docs.python.org/3/library/argparse.html?highlight=argumentparser#argumentparser-objects) for the details.
"""

parser = argparse.ArgumentParser(
Expand Down Expand Up @@ -726,12 +711,12 @@ def set_exit_code(self, exit_code: typing.Union[int, str], force: bool = False):
# Time

def time(self) -> float:
'''
"""
Return UTC UNIX timestamp using a loop time (a fast way how to get a wall clock time).

Returns:
Current UTC UNIX timestamp.
'''
"""
return self.BaseTime + self.Loop.time()


Expand Down
49 changes: 27 additions & 22 deletions docs/reference/application/reference.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ creating a subclass. There should be only one `Application` object in the proces

!!! example "Creating a new ASAB application:"

To create a new ASAB application, just create a subclass of `asab.Application` object and use the `run()` method:
To create a new ASAB application, just create a subclass of `asab.Application` object and use the [`run()`](#asab.application.Application.run) method:

```python title='app.py'
import asab
Expand All @@ -32,7 +32,7 @@ creating a subclass. There should be only one `Application` object in the proces

The app will be running until you stop it by `Ctrl+C`.

To create an application that performs some operations and then stops, use the `stop()` method.
To create an application that performs some operations and then stops, use the [`stop()`](#asab.application.Application.stop) method.

```python title='app_that_terminates.py'
import asab
Expand Down Expand Up @@ -141,33 +141,38 @@ class MyApplication(asab.Application):

## Command-line parser

Creates an `argparse.ArgumentParser`. This method can be overloaded to
adjust command-line argument parser.
The method [`create_argument_parser()`](#asab.application.Application.create_argument_parser) creates an [`argparse.ArgumentParser`](https://docs.python.org/3/library/argparse.html). This method can be overloaded to adjust command-line argument parser.

Please refer to Python standard library `argparse` for more details
about function arguments.
The application object calls this method during *init-time* to process a command-line arguments.
You can overload this method to provide your own implementation of command-line argument parser.

The application object calls this method during init-time to process a
command-line arguments. `argparse` is
used to process arguments. You can overload this method to provide your
own implementation of command-line argument parser.
The `Description` attribute is a text that will be displayed in a help text (`--help`).
It is expected that own value will be provided. The default value is `""` (empty string).

The `Description` attribute is a text
that will be displayed in a help text (`--help`). It is expected that
own value will be provided. The default value is `""` (empty string).
Default ASAB arguments:

| Argument | Type | Action |
| :----- | :----- | :----- |
| `-c`, `--config` | str | Specify a path to a configuration file. |
| `-d`, `--daemonize` | bool | Run daemonized (in the background). |
| `-k`, `--kill` | bool | Kill a running daemon and quit. |
| `-l`, `--log-file` | str | Specify a path to a log file. |
| `-s`, `--syslog`| bool | Enable logging to a syslog. |
| `-v`, `--verbose` | bool | Print more information (enable debug output). |
| `-w`, `--web-api` | str | Activate Asab web API (default listening port is 0.0.0.0:8080). |
| `--startup-housekeeping` | | Trigger housekeeping event immediately after application startup. |

## UTC Time

Return the current \"event loop time\" in seconds since the epoch as a
floating point number. The specific date of the epoch and the handling
of leap seconds is platform dependent. On Windows and most Unix systems,
the epoch is January 1, 1970, 00:00:00 (UTC) and leap seconds are not
counted towards the time in seconds since the epoch. This is commonly
referred to as Unix time.
The method [`time()`](#asab.application.Application.time) returns the current "event loop time"
in seconds since the epoch as a floating point number.
The specific date of the epoch and the handling of leap seconds is platform dependent.
On Windows and most Unix systems, the epoch is January 1, 1970, 00:00:00 (UTC)
and leap seconds are not counted towards the time in seconds since the epoch.
This is commonly referred to as Unix time.

A call of the `time.time()` function could be expensive. This method
provides a cheaper version of the call that returns a current wall time
in UTC.
A call of the `time.time()` function could be expensive.
This method provides a cheaper version of the call that returns a current wall time in UTC.

---
## Reference
Expand Down
2 changes: 1 addition & 1 deletion docs/reference/modules_services/reference.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@ def custom_function():

1. The method [`add_module()`](/reference/application/reference/#asab.Application.add_module) initializes and adds a new module.
The `module_class` class will be instantiated during the method call.
2. The method [`get_service()`](#asab.Application.get_service) locates a service by its name and returns the [`asab.Service`](#asab.Service) object.
2. The method [`get_service()`](reference/application/reference/#asab.Application.get_service) locates a service by its name and returns the [`asab.Service`](#asab.Service) object.
3. Modules that has been added to the application are stored in [`asab.Application.Modules`](/reference/application/reference/#asab.application.Application.Modules) list. Similarly, Services are stored in [`asab.Application.Services`](/reference/application/reference/#asab.Application.Services) dictionary.


Expand Down
17 changes: 6 additions & 11 deletions docs/reference/storage/reference.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -46,16 +46,13 @@ objects, updating existing objects and deleting them.
u = storage.upsertor("test-collection")
```

The `StorageService.upsertor()`{.interpreted-text role="func"} method
creates an upsertor object associated with the specified collection. It
takes [collection]{.title-ref} as an argument and can have two
parameters [obj\_id]{.title-ref} and [version]{.title-ref}, which are
used for getting an existing object by its ID and version.
The `StorageService.upsertor()` method creates an upsertor object associated with the specified collection.
It takes `collection` as an argument and can have two
parameters `obj_id` and `version`, which are used for getting an existing object by its ID and version.

### Inserting an object

For inserting an object to the collection, use the
`Upsertor.set()`{.interpreted-text role="func"} method.
For inserting an object to the collection, use the `Upsertor.set()` method.

``` python
u.set("key", "value")
Expand Down Expand Up @@ -143,8 +140,7 @@ a dictionary where all the collections are stored in.

!!! note

You can go through all the databases directly by accessing
[InMemoryCollections]{.title-ref} attribute, although we do not
You can go through all the databases directly by accessing `InMemoryCollections` attribute, although we do not
recommend that.

``` python
Expand All @@ -157,8 +153,7 @@ a dictionary where all the collections are stored in.

If the option `mongodb` is set, ASAB will store data in MongoDB database.

ASAB uses [motor library](https://pypi.org/project/motor/) which
provides non-blocking MongoDB driver for [asyncio]{.title-ref}.
ASAB uses [motor library](https://pypi.org/project/motor/) which provides non-blocking MongoDB driver for asyncio.

You can specify the database name and URL for MongoDB in config file
(the following example is the default configuration):
Expand Down