kore-doc

The kore documentation found under https://docs.kore.io/
Commits | Files | Refs | README | git clone https://git.kore.io/kore-doc.git

python.md (42751B)



      1 # Python
      2 
      3 This page contains a reference of all exported Kore functions to Python.
      4 
      5 Kore must be compiled with **PYTHON=1** for this to work.
      6 Python 3.6 or higher should be used.
      7 
      8 ---
      9 
     10 # A Kore Python application
     11 
     12 Since Kore 4.x you can use Kore as an asynchronous first Python web development platform.
     13 
     14 Completely configurable via code and easy to setup and write.
     15 
     16 A Kore Python application must be setup in the following way:
     17 
     18 * Import kore.
     19 * Define a class with a configure() method.
     20 * Instantiate the koreapp global with that class.
     21 
     22 The configure() method is called at startup by the Kore platform and
     23 will receive a list of arguments passed to the command-line.
     24 
     25 From there you can configure Kore via the kore.config object, create
     26 server contexts and setup domains and routes.
     27 
     28 Note that the Python code is expected to run inside of the Kore worker
     29 process, the kore module being imported is not available outside of
     30 this worker process.
     31 
     32 Example:
     33 
     34 ```python
     35 import kore
     36 
     37 class MyApp:
     38     def configure(self, args):
     39         kore.config.workers = 1
     40         kore.config.deployment = "dev"
     41 
     42         kore.server(name="notls", ip="127.0.0.1", port="8888", tls=False)
     43 
     44         domain = kore.domain("kore.io", attach="notls")
     45         domain.route("/", self.index, methods=["get"])
     46         domain.route("^/(0-9)$", self.index_with_args, methods=["get"])
     47 
     48     def index(self, req):
     49         req.response(200, b'hello')
     50 
     51     def index_with_args(self, req, specified_id):
     52         req.response(200, specified_id)
     53 
     54 koreapp = MyApp()
     55 ```
     56 
     57 ## Index
     58 
     59 * [Kore module](#koremodule)
     60   * [configuration](#koreconfig)
     61   * [constants](#koremoduleconstants)
     62   * [functions](#koremodulefunctions)
     63     * [server](#server)
     64     * [domain](#domain)
     65       * [route](#domainroute)
     66       * [filemaps](#filemaps)
     67     * [log](#log)
     68     * [timer](#timer)
     69     * [proc](#proc)
     70     * [fatal](#fatal)
     71     * [tracer](#tracer)
     72     * [task\_create](#taskcreate)
     73     * [task\_kill](#taskkill)
     74     * [gather](#gather)
     75     * [suspend](#suspend)
     76     * [httpclient](#httpclient)
     77     * [dbsetup](#dbsetup)
     78     * [dbquery](#dbquery)
     79     * [websocket\_broadcast](#websocketbroadcast)
     80     * [worker](#worker)
     81     * [setname](#setname)
     82     * [coroname](#coroname)
     83     * [corotrace](#corotrace)
     84     * [privsep](#privsep)
     85 
     86 
     87 * [Http module](#httpmodule)
     88   * [constants](#httpmoduleconstants)
     89   * [functions](#httpmodulefunctions)
     90     * [pgsql](#pgsql)
     91     * [cookie](#cookie)
     92     * [response](#response)
     93     * [argument](#argument)
     94     * [body\_read](#bodyread)
     95     * [file\_lookup](#filelookup)
     96     * [populate\_get](#populateget)
     97     * [populate\_post](#populatepost)
     98     * [populate\_cookies](#populatecookies)
     99     * [populate\_multipart](#populatemultipart)
    100     * [request\_header](#requestheader)
    101     * [response\_header](#responseheader)
    102     * [websocket\_handshake](#websockethandshake)
    103 
    104 
    105 * [Asynchronous functions](#async)
    106   * [Sockets](#asyncsocket)
    107   * [Locks](#asynclock)
    108   * [Queues](#asyncqueue)
    109   * [Processes](#asyncproc)
    110 
    111 
    112 * [Asynchronous libcurl support](#curl)
    113  * [curl](#curlhandle)
    114  * [setopt](#curlsetopt)
    115 
    116 # Kore {#koremodule}
    117 
    118 ## Configuration {#koreconfig}
    119 
    120 Kore configuration options can be set via the kore.config module.
    121 
    122 All options available in the traditional kore configuration be
    123 set via the Python code.
    124 
    125 | Configuration option | Description |
    126 | --- | --- |
    127 | workers | The number of worker processes to use. If not set, the number of CPU cores in the system. |
    128 | worker\_max\_connections | The maximum number of active connections a worker process holds before refusing to accept more. |
    129 | worker\_rlimit\_nofiles | The maximum number of open file descriptor per worker. |
    130 | worker\_accept\_threshold | The maximum number of new connections to accept in a single event loop. |
    131 | worker\_death\_policy | The death policy for a worker, "restart" by default. If set to "terminate" will cause the Kore server to shutdown on abnormal worker termination. |
    132 | worker\_set\_affinity | Worker CPU affinity (0 or 1, default 1). |
    133 | pidfile | The path to a file in which the server will write the PID for the parent process. |
    134 | socket\_backlog | The number of pending connections. |
    135 | tls\_version | The TLS version to use (default: both, 1.2 for TLSv1.2 only and 1.3 for TLSv1.3 only). |
    136 | tls\_cipher | OpenSSL ciphersuite list to use. Defaults to a very sane list with only AEAD ciphers and ephemeral key exchanges. |
    137 | tls\_dhparam | Path to DH parameters for the server to use. |
    138 | rand\_file | Path to a 2048 byte file containing entropy used to seed the PRNG. |
    139 | acme\_email | An email address used for account registration. |
    140 | acme\_provider | A URL to the directory for an ACME provider. Defaults to Let's Encrypt. |
    141 | pledge | OpenBSD only, pledge categories for the worker processes. |
    142 | seccomp\_tracing | Linux only, seccomp violations will be logged and not cause the process to terminate. Either "yes" or "no". |
    143 | filemap\_ext | The default extension for files in a filemap. |
    144 | filemap\_index | The root file in a filemap. (eg index.html). |
    145 | http\_media\_type | Add a new HTTP media type (in the form of "mediatype ext1 ext2 ext"). |
    146 | http\_header\_max | The maximum number of bytes HTTP headers can consist of. If a request comes in with headers larger than this the connection is closed. Defaults to 4096 bytes. |
    147 | http\_header\_timeout | The number of seconds after which Kore will close a connection if no HTTP headers were received. Defaults to 10. |
    148 | http\_body\_max | The maximum number of bytes an HTTP body can consist of. If a request comes in with a body larger than this the connection is closed with a 413 response. Defaults to 1MB. |
    149 | http\_body\_timeout | The number of seconds after which Kore will close a connection if no HTTP body was received in full. Defaults to 60. |
    150 | http\_body\_disk\_offload | The number in bytes from which point Kore will offload incoming HTTP bodies onto a file on disk instead of keeping it in memory. Disabled by default. |
    151 | http\_body\_disk\_path | A path where the temporary body files are written if the http\_body\_disk\_offload setting is enabled. |
    152 | http\_server\_version | Allows you to override the Kore server header. |
    153 | http\_pretty\_error | If set to "yes" will display HTML based HTTP error codes. Defaults to "no". |
    154 | logfile | Set the logfile to which Kore will write all worker output. |
    155 | deployment | The deployment type of the application. Either "production", "development" or "docker". The production setting will cause Kore to chroot and drop privileges and run in the background. The development setting will run Kore in the foreground and only chdir into the root setting. The docker setting will cause Kore to run in the foreground but still apply priviledge separation. |
    156 
    157 Any configuration options should be set in your App.configure method.
    158 
    159 Example
    160 
    161 ```python
    162 import os
    163 import kore
    164 
    165 class MyApp:
    166     def configure(self, args):
    167         kore.config.workers = 1
    168         kore.config.http_header_max = 1024
    169         kore.config.http_header_timeout = 60
    170         kore.config.seccomp_tracing = "yes"
    171         kore.config.deployment = os.getenv("DEPLOYMENT", default="dev")
    172 
    173 ```
    174 
    175 ## Constants {#koremoduleconstants}
    176 
    177 The kore module exports some constants that can be used by the Python code.
    178 
    179 * LOG\_INFO
    180 * LOG\_NOTICE
    181 * LOG\_ERR
    182 * RESULT\_OK
    183 * RESULT\_RETRY
    184 * RESULT\_ERROR
    185 * MODULE\_LOAD
    186 * MODULE\_UNLOAD
    187 * TIMER\_ONESHOT
    188 * CONN\_PROTO\_HTTP
    189 * CONN\_PROTO\_UNKNOWN
    190 * CONN\_PROTO\_WEBSOCKET
    191 * CONN\_STATE\_ESTABLISHED
    192 
    193 If Kore was built with CURL=1 all curl\_easy\_setopt CURLoption constants
    194 are exported via the kore module as well.
    195 
    196 ## Functions {#koremodulefunctions}
    197 
    198 ---
    199 
    200 # server {#server}
    201 
    202 ### Synopsis
    203 
    204 ```python
    205 kore.server(name, ip="ip", port="port", path="/tmp/web.sock", tls=True)
    206 ```
    207 
    208 ### Description
    209 
    210 Setup a new server with the given **name**.
    211 
    212 The ip and path keywords are mutually exclusive.
    213 
    214 | Parameter | Description |
    215 | --- | --- |
    216 | name | The name of this listener. |
    217 
    218 | Keyword | Description |
    219 | --- | --- |
    220 | ip | This keyword specifies the IP address to bind to. |
    221 | port | This keyword specifies the port to bind to. |
    222 | path | This keyword specifies the UNIX path to bind to. |
    223 | tls | This keyword specifies if TLS is enabled or not (True by default). |
    224 
    225 ### Returns
    226 
    227 Nothing
    228 
    229 ### Example
    230 
    231 ```python
    232 kore.server("default", ip="127.0.0.1", port="8888", tls=False)
    233 ```
    234 
    235 ---
    236 
    237 # domain {#domain}
    238 
    239 ### Synopsis
    240 
    241 ```python
    242 kore.domain(host, attach="server", cert="cert.pem", key="key.pem", acme=False,
    243     client_verify="ca.pem", verify_depth=1)
    244 ```
    245 
    246 ### Description
    247 
    248 Setup a new domain for **host** attached to the given server.
    249 
    250 | Parameter | Description |
    251 | --- | --- |
    252 | host | The hostname of this domain (eg: kore.io). |
    253 
    254 The cert and key keywords should not be specified if acme is True.
    255 
    256 | Keyword | Description |
    257 | --- | --- |
    258 | attach | Attach this domain to the given server name. |
    259 | cert | The path to the certificate for this domain. |
    260 | key | The path to the private key for this domain. |
    261 | acme | If true will use the configured ACME provider (let's encrypt by default) to automatically obtain an X509 for this domain. |
    262 | client\_verify | If present points to a PEM file containing a Certificate Authority for which the client should present a certificate for. |
    263 | verify\_depth | Maximum depth for the certificate chain. |
    264 
    265 ### Returns
    266 
    267 A domain handle on which you can install routes.
    268 
    269 ### Example
    270 
    271 ```python
    272 dom = kore.domain("kore.io", attach="server", acme=True)
    273 dom.route("/", self.index, methods=["get"])
    274 ```
    275 
    276 ---
    277 
    278 # domain.route {#domainroute}
    279 
    280 ### Synopsis
    281 
    282 ```python
    283 domain.route(url, callback, methods=[], methodname={}, auth=None)
    284 ```
    285 
    286 ### Description
    287 
    288 Setup a new route in the domain. The route is attached to the given
    289 **url** and will call the **callback** function when hit.
    290 
    291 | Parameter | Description |
    292 | --- | --- |
    293 | url | URL for this route, can contain regex and capture groups. Each capture group is passed as a separate parameter to the callback after the initial request object. |
    294 | callback | The callback to call for this route. This callback takes at least one parameter: the request object. |
    295 
    296 | Keyword | Description |
    297 | --- | --- |
    298 | methods | A list of allowed methods. Any request to this route with an incorrect method will automatically result in a 405. |
    299 | key | The path to the private key for this domain. |
    300 | methodname | For each supported method a dictionary containing parameters for the route and how they are validated. |
    301 | auth | If set should be a dictionary containing the authentication information for the route. |
    302 
    303 ### Returns
    304 
    305 Nothing
    306 
    307 ### Example
    308 
    309 ```python
    310 import kore
    311 import json
    312 
    313 class RouteExample:
    314     def configure(self, args):
    315         kore.config.workers = 1
    316         kore.config.deployment = "dev"
    317 
    318         kore.server("default", ip="127.0.0.1", port="8888", tls=False)
    319         dom = kore.domain("*", attach="default")
    320 
    321         # Simple GET route.
    322         dom.route("/", self.index, methods=["get"])
    323 
    324         # Example post route with some arguments (which are validated
    325         # automatically and removed if verification fails).
    326         dom.route("/update", self.update, methods=["post"],
    327             post={
    328                 "number"   : "^[0-9]{4}$",
    329                 "user"     : "^[a-z]{4,12}$"
    330             }
    331         )
    332 
    333         # Authenticate via header or cookie.
    334         dom.route("/secret", self.secret, methods=["get"],
    335             auth={
    336                 "type"     : "header",      # header or cookie
    337                 "value"    : "x-header",    # header or cookie name
    338                 "redirect" : "/",           # redirect location upon failure,
    339                                             # if not set, 403 is returned.
    340                 "verify"   : self.verify    # The callback to verify
    341             }
    342         )
    343 
    344     def verify(self, req, data):
    345         kore.log(kore.LOG_INFO, "verify called with %s" % data)
    346         return True
    347 
    348     def index(self, req):
    349         req.response(200, b'this is the index')
    350 
    351     def secret(self, req):
    352         req.response(200, b'this is the secret')
    353 
    354     def update(self, req):
    355         req.populate_post()
    356 
    357         payload = {}
    358         nr = req.argument("number")
    359         user = req.argument("user")
    360 
    361         if nr:
    362             payload.update({"number": nr})
    363         if user:
    364             payload.update({"user": user})
    365 
    366         req.response(200, json.dumps(payload).encode())
    367 
    368 koreapp = RouteExample()
    369 ```
    370 
    371 ---
    372 
    373 # domain.filemaps {#filemaps}
    374 
    375 ### Synopsis
    376 
    377 ```python
    378 domain.filemaps(maps)
    379 ```
    380 
    381 ### Description
    382 
    383 Add [filemaps](https://docs.kore.io/4.1.0/applications/filemap.html) to the domain.
    384 
    385 | Parameter | Description |
    386 | --- | --- |
    387 | maps | A dict containing the filemaps. The key is the URL part, the value is the local part on disk relative to the root of the worker process. |
    388 
    389 ### Returns
    390 
    391 Nothing
    392 
    393 ### Example
    394 
    395 ```python
    396 import kore
    397 
    398 class FileMap:
    399     def configure(self, args):
    400         kore.config.workers = 1
    401         kore.config.deployment = "dev"
    402 
    403         kore.server("default", ip="127.0.0.1", port="8888", tls=False)
    404         dom = kore.domain("*", attach="default")
    405         dom.filemaps({ "/": "webroot"})
    406 
    407 koreapp = FileMap()
    408 ```
    409 
    410 ---
    411 
    412 # log {#log}
    413 
    414 ### Synopsis
    415 
    416 ```python
    417 kore.log(priority, string)
    418 ```
    419 
    420 ### Description
    421 
    422 Logs the given string to syslog.
    423 
    424 | Parameter | Description |
    425 | --- | --- |
    426 | priority | Log level priority (kore.LOG\_ constants). |
    427 | string | The string to be sent to syslog. |
    428 
    429 ### Returns
    430 
    431 Nothing
    432 
    433 ### Example
    434 
    435 ```python
    436 kore.log(kore.LOG_INFO, 'this is a log string from a worker process')
    437 ```
    438 
    439 ---
    440 
    441 # timer {#timer}
    442 
    443 ### Synopsis
    444 
    445 ```python
    446 kore.timer(method, delay, flags)
    447 ```
    448 
    449 ### Description
    450 
    451 Creates a timer that will run after **delay** milliseconds and call the
    452 **method** specified when expires.
    453 
    454 A timer can be primed to run at intervals or as a one-shot occasion.
    455 
    456 For a intervals, **flags** is 0 while for one-shot **flags** should
    457 be **kore.TIMER\_ONESHOT**
    458 
    459 A kore.timer object may be stopped by calling the **close** method on it.
    460 
    461 | Parameter | Description |
    462 | --- | --- |
    463 | method | The method to call when the timer fires. |
    464 | delay | The delay in milliseconds before the timer fires. |
    465 | flags | Either 0 for an interval timer or kore.TIMER_ONESHOT for a one-shot timer. |
    466 
    467 ### Returns
    468 
    469 A kore.timer object.
    470 
    471 ### Example
    472 
    473 ```python
    474 def callback():
    475 	print("called")
    476 
    477 mytimer = kore.timer(callback, 100, kore.TIMER\_ONESHOT)
    478 
    479 # Stop the timer.
    480 mytimer.close()
    481 ```
    482 
    483 ---
    484 
    485 # proc {#proc}
    486 
    487 ### Synopsis
    488 
    489 ```python
    490 kore.proc(command, optional_timeout)
    491 ```
    492 
    493 ### Description
    494 
    495 Spawns a new process with the given **command** and optional **timeout** in
    496 milliseconds.
    497 
    498 If timeout is non-zero Kore will raise TimeoutError if the process has not
    499 exited before the timeout expires.
    500 
    501 If a TimeoutError exception occurs the process is still active and **must**
    502 be killed by calling the **kill** method on the process object.
    503 
    504 See the [asynchronous process](#asyncproc) section for more.
    505 
    506 | Parameter | Description |
    507 | --- | --- |
    508 | command | The command to be executed. |
    509 | timeout | Optional timeout in milliseconds. |
    510 
    511 ### Returns
    512 
    513 A kore.proc object.
    514 
    515 ### Example
    516 
    517 ```python
    518 async def request(req):
    519 	proc = kore.proc("ls -l /tmp")
    520 
    521 	try:
    522 		stdout = await proc.recv(8192)
    523 		retcode = proc.reap()
    524 		req.response(200, stdout)
    525 	except TimeoutError:
    526 		proc.kill()
    527 		print("process timed out")
    528 		req.response(500, b'')
    529 ```
    530 
    531 ---
    532 
    533 # fatal {#fatal}
    534 
    535 ### Synopsis
    536 
    537 ```python
    538 kore.fatal(reason)
    539 ```
    540 
    541 ### Description
    542 
    543 Terminates the worker process with the given reason as the error message.
    544 
    545 | Parameter | Description |
    546 | --- | --- |
    547 | reason | String containing the reason why the worker is terminating. |
    548 
    549 ### Returns
    550 
    551 Nothing
    552 
    553 ### Example
    554 
    555 ```python
    556 kore.fatal('worker going dead')
    557 ```
    558 
    559 ---
    560 
    561 # tracer {#tracer}
    562 
    563 ### Synopsis
    564 
    565 ```python
    566 kore.tracer(method)
    567 ```
    568 
    569 ### Description
    570 
    571 Sets the callback Kore will call for any uncaught exceptions.
    572 
    573 The callback will get 3 parameters:
    574 * The exception type
    575 * The exception value
    576 * The traceback
    577 
    578 | Parameter | Description |
    579 | --- | --- |
    580 | method | The method to call for uncaught exceptions. |
    581 
    582 ### Returns
    583 
    584 Nothing
    585 
    586 ### Example
    587 
    588 ```python
    589 import traceback
    590 
    591 def tracer(etype, value, tb):
    592 	traceback.print_exception(etype, value, tb)
    593 
    594 def kore_parent_configure(args):
    595 	kore.tracer(tracer)
    596 ```
    597 
    598 ---
    599 
    600 # task\_create {#taskcreate}
    601 
    602 ### Synopsis
    603 
    604 ```python
    605 kore.task_create(method)
    606 ```
    607 
    608 ### Description
    609 
    610 Creates a new task that will run the given method.
    611 
    612 | Parameter | Description |
    613 | --- | --- |
    614 | method | The method to call from the new task. |
    615 
    616 ### Returns
    617 
    618 The unique task identifier that can be passed to kore.task\_kill().
    619 
    620 ### Example
    621 
    622 ```python
    623 import kore
    624 
    625 async def coro(id):
    626 	print("i am coro %d" % id)
    627 
    628 def kore_worker_configure():
    629 	kore.task_create(coro(1))
    630 	kore.task_create(coro(2))
    631 ```
    632 
    633 ---
    634 
    635 # task\_kill {#taskkill}
    636 
    637 ### Synopsis
    638 
    639 ```python
    640 kore.task_kill(taskid)
    641 ```
    642 
    643 ### Description
    644 
    645 Kills the coroutine task specified in the **taskid** identifier.
    646 
    647 The coroutine will immediately be killed.
    648 
    649 | Parameter | Description |
    650 | --- | --- |
    651 | taskid | The taskid identifier to be killed. |
    652 
    653 ### Returns
    654 
    655 Nothing
    656 
    657 ### Example
    658 
    659 ```python
    660 import kore
    661 
    662 async def coro(id):
    663 	while True:
    664 		await kore.suspend(1000)
    665 		print("i am coro %d" % id)
    666 
    667 async def kill(taskid):
    668 	await kore.suspend(5000)
    669 	kore.task_kill(taskid)
    670 
    671 def kore_worker_configure():
    672 	task = kore.task_create(coro(1))
    673 
    674 	kore.task_create(kill(task))
    675 ```
    676 
    677 ---
    678 
    679 # gather {#gather}
    680 
    681 ### Synopsis
    682 
    683 ```python
    684 kore.gather(coroutines)
    685 ```
    686 
    687 ### Description
    688 
    689 Awaits all given coroutines and returns their result in a list.
    690 
    691 If a coroutine throws an exception that exception is returned as the
    692 result for that coroutine.
    693 
    694 | Parameter | Description |
    695 | --- | --- |
    696 | coroutines | The coroutines to wait for. |
    697 
    698 | Keywords | Description |
    699 | --- | --- |
    700 | concurrency | The number of coroutines to run at the same time. |
    701 
    702 ### Returns
    703 
    704 Nothing
    705 
    706 ### Example
    707 
    708 ```python
    709 import kore
    710 
    711 async def coro(id):
    712 	print("i am coro %d" % id)
    713 
    714 async def request(req):
    715 	results = await kore.gather(coro(1), coro(2))
    716 
    717 	for result in results:
    718 		if isinstance(result, Exception):
    719 			raise result
    720 		print("result is %s" % result)
    721 
    722 	req.response(200, b'')
    723 ```
    724 
    725 ---
    726 
    727 # suspend {#suspend}
    728 
    729 ### Synopsis
    730 
    731 ```python
    732 kore.suspend(milliseconds)
    733 ```
    734 
    735 ### Description
    736 
    737 Suspends the current coroutine for the specified amount of milliseconds.
    738 
    739 This function must be awaited.
    740 
    741 | Parameter | Description |
    742 | --- | --- |
    743 | milliseconds | Number of milliseconds to suspend execution for. |
    744 
    745 ### Returns
    746 
    747 Nothing
    748 
    749 ### Example
    750 
    751 ```python
    752 import kore
    753 
    754 async def request(req):
    755 	await kore.suspend(1000)
    756 	req.response(200, b'')
    757 ```
    758 
    759 ---
    760 
    761 # dbsetup {#dbsetup}
    762 
    763 ### Synopsis
    764 
    765 ```python
    766 kore.dbsetup(name, connection_string)
    767 ```
    768 
    769 ### Description
    770 
    771 Associates a pgsql connection string with a shortname for a database that
    772 can be used later via <a href="#dbquery">dbquery</a>.
    773 
    774 | Parameter | Description |
    775 | --- | --- |
    776 | name | The friendly name for the database. |
    777 | connection\_string | The pgsql connection string. |
    778 
    779 ### Returns
    780 
    781 Nothing
    782 
    783 ### Example
    784 
    785 ```python
    786 kore.dbsetup("db", "host=/tmp dbname=hello")
    787 ```
    788 
    789 ---
    790 
    791 # dbquery {#dbquery}
    792 
    793 ### Synopsis
    794 
    795 ```python
    796 result = await kore.dbquery(db, query, params=[v1, v2, ...])
    797 ```
    798 
    799 ### Description
    800 
    801 Performs an asynchronous PostgreSQL query. The query should be a parameterized
    802 and the arguments for each parameter are passed via the **params** keyword.
    803 
    804 | Parameter | Description |
    805 | --- | --- |
    806 | db | A previously configured database name. |
    807 | query | The query to be performed. |
    808 | params | A list of strings or byte object arguments. |
    809 
    810 ### Returns
    811 
    812 The result of the query as a dictionary where each key is the column name
    813 and the matching value for that column.
    814 
    815 If the returned data for a column was binary the returned value will be
    816 of the **bytes** type, otherwise the returned value will be a python string.
    817 
    818 ### Example
    819 
    820 ```python
    821 async def myquery(req):
    822 	name = "bar"
    823 	result = await kore.dbquery("db",
    824 		"SELECT * FROM table WHERE foo = $1", params=[name])
    825 	req.response(200, json.dumps(result).encode("utf-8"))
    826 ```
    827 
    828 ---
    829 
    830 ## Asynchronous HTTP client {#httpclient}
    831 
    832 The Python API in Kore contains a full asynchronous HTTP client that allows
    833 you to fire off HTTP requests from your Python code and await their result.
    834 
    835 Before you can use the client you must set it up.
    836 
    837 **note** Kore must be built with CURL=1 for the httpclient to be included.
    838 
    839 ```python
    840 client = kore.httpclient(url, keywords)
    841 ```
    842 
    843 | Parameter | Description |
    844 | --- | --- |
    845 | url | The URL to send the request to. |
    846 
    847 Addiotnally, optional keyword parameters can be specified:
    848 
    849 | Keywords | Description |
    850 | --- | --- |
    851 | tlscert | A path to an x509 certificate to be used to authenticate this request. |
    852 | tlskey | A path to the private key to be used to authenticate this request. |
    853 | tlsverify | Should the peer its x509 certificate be verified (default: True). |
    854 | cabundle | A path to a PEM bundle containing the CAs you would like to use to verify the peer. |
    855 | unix | Use this unix socket path instead (On Linux if prefixed with '@' this becomes an abstract socket path. |
    856 | curlopt | A dictionary containing additional curl options and their settings. |
    857 
    858 Kore internally will re-use connections to the same hosts if they are
    859 available, as a developer you can go ahead and create multiple httpclient
    860 objects to the same host, they will all share underlying connections.
    861 
    862 Once the httpclient object is created you can call any of the following
    863 functions on it to perform the requested action (these calls return a coroutine and must be awaited):
    864 
    865 * get
    866 * put
    867 * post
    868 * head
    869 * patch
    870 * delete
    871 * options
    872 
    873 | Keywords | Description |
    874 | --- | --- |
    875 | body | For put, post and patch, add the given bytes as the HTTP body. |
    876 | headers | A dictionary containing the headers to be added to the request. |
    877 | return\_headers | Set to True to return the headers as well (default: False). |
    878 | curlopt | A dictionary containing additional curl options and their settings. |
    879 
    880 Unless the return\_headers keyword is True, these functions return a tuple
    881 containing the status and HTTP body. If return\_headers is True, the tuple
    882 returned will be status, headers, HTTP body.
    883 
    884 Any curlopt entries given inside of the action calls will override
    885 the options set on the httpclient context.
    886 
    887 ### Example
    888 
    889 ```python
    890 client = kore.httpclient("https://kore.io",
    891 	curlopt={
    892 		kore.CURLOPT_TIMEOUT: 120
    893 	})
    894 
    895 # Do a normal GET request.
    896 status, body = await client.get()
    897 
    898 # Do a POST.
    899 mybody = "Hello world"
    900 status, body = await client.post(
    901 	body=mybody.encode("utf-8"),
    902 	headers={
    903 		"x-header": "from-client"
    904 	},
    905 	curlopt={
    906 		kore.CURLOPT_TIMEOUT: 60
    907 	}
    908 )
    909 
    910 # Get the headers from a GET request.
    911 status, headers, body = await client.get(return_headers=True)
    912 ```
    913 
    914 ---
    915 
    916 ## Asynchronous libcurl client {#curl}
    917 
    918 The Python API in Kore contains a full asynchronous libcurl client that allows
    919 you to fire off any protocol that libcurl supports from your Python code and
    920 await their result.
    921 
    922 Before you can use the client you must set it up.
    923 
    924 **note** Kore must be built with CURL=1 for the curl handler to be included.
    925 
    926 ---
    927 
    928 # Creating a new curl handle {#curlhandle}
    929 
    930 ### Synopsis
    931 
    932 ```python
    933 handle = kore.curl(url)
    934 ```
    935 
    936 | Parameter | Description |
    937 | --- | --- |
    938 | url | The URL to send the request to. |
    939 
    940 Once the libcurl object is created you can call handle.run() to perform
    941 the call to the specified url.
    942 
    943 Additionally you can call handle.setopt() which behaves a lot like
    944 the curl\_easy\_setopt() function.
    945 ### Example
    946 
    947 ```python
    948 handle = kore.curl("https://kore.io")
    949 
    950 # Run the libcurl handle.
    951 data = await handle.run()
    952 ```
    953 
    954 ---
    955 
    956 # Using libcurl setopt from Python {#curlsetopt}
    957 
    958 ### Synopsis
    959 
    960 ```python
    961 handle.setopt(option, value)
    962 ```
    963 
    964 | Parameter | Description |
    965 | --- | --- |
    966 | option | The libcurl option to be set. |
    967 | value | The value to set the option to. |
    968 
    969 All libcurl constants are exported under the kore module directly.
    970 
    971 Example:
    972 ```python
    973 handle = kore.curl("https://kore.io")
    974 handle.setopt(kore.CURLOPT_TIMEOUT, 10)
    975 ```
    976 
    977 Depending on what the original option in libcurl takes the value must
    978 either be a string, an integer or a list.
    979 
    980 ---
    981 
    982 # websocket\_broadcast {#websocketbroadcast}
    983 
    984 ### Synopsis
    985 
    986 ```python
    987 kore.websocket_broadcast(src, op, data, scope)
    988 ```
    989 
    990 ### Description
    991 
    992 Broadcasts a websocket message to all other connected websocket clients.
    993 
    994 | Parameter | Description |
    995 | --- | --- |
    996 | src | The source **kore.connection** object. |
    997 | op | The websocket op type. |
    998 | data | The data to be broadcasted. |
    999 | scope | Whether or not this is broadcasted to all workers or just this one. |
   1000 
   1001 ### Returns
   1002 
   1003 Nothing
   1004 
   1005 ### Example
   1006 
   1007 ```python
   1008 def onmessage(c, op, data):
   1009 	kore.websocket_broadcast(c, op, data, kore.WEBSOCKET_BROADCAST_GLOBAL)
   1010 ```
   1011 
   1012 ---
   1013 
   1014 # worker {#worker}
   1015 
   1016 ### Synopsis
   1017 
   1018 ```python
   1019 kore.worker()
   1020 ```
   1021 
   1022 ### Description
   1023 
   1024 Returns the worker ID the code is currently running under.
   1025 
   1026 ### Returns
   1027 
   1028 The worker ID.
   1029 
   1030 ### Example
   1031 
   1032 ```python
   1033 kore.log(kore.LOG_INFO, "running on %d" % kore.worker())
   1034 ```
   1035 
   1036 ---
   1037 
   1038 # setname {#setname}
   1039 
   1040 ### Synopsis
   1041 
   1042 ```python
   1043 kore.setname(name)
   1044 ```
   1045 
   1046 ### Description
   1047 
   1048 Sets the kore\_progname variable which is used when constructing
   1049 proctitle.
   1050 
   1051 ### Returns
   1052 
   1053 Nothing
   1054 
   1055 ### Example
   1056 
   1057 ```python
   1058 kore.setname("myapp")
   1059 ```
   1060 
   1061 ---
   1062 
   1063 # coroname {#coroname}
   1064 
   1065 ### Synopsis
   1066 
   1067 ```python
   1068 kore.coroname(name)
   1069 ```
   1070 
   1071 ### Description
   1072 
   1073 Sets the current coroutine its friendly name. This name is used when
   1074 coroutine tracing is enabled in its output.
   1075 
   1076 ### Returns
   1077 
   1078 Nothing
   1079 
   1080 ### Example
   1081 
   1082 ```python
   1083 kore.coroname("consumer")
   1084 ```
   1085 
   1086 ---
   1087 
   1088 # corotrace {#corotrace}
   1089 
   1090 ### Synopsis
   1091 
   1092 ```python
   1093 kore.corotrace(enabled)
   1094 ```
   1095 
   1096 ### Description
   1097 
   1098 Enables or disable coroutine tracing.
   1099 
   1100 If enabled the application will print out all coroutines their
   1101 suspend / resume activities and where in the Python code this
   1102 is happening.
   1103 
   1104 ### Returns
   1105 
   1106 Nothing
   1107 
   1108 ### Example
   1109 
   1110 ```python
   1111 kore.corotrace(True)
   1112 ```
   1113 
   1114 ---
   1115 
   1116 # privsep {#privsep}
   1117 
   1118 ### Synopsis
   1119 
   1120 ```python
   1121 kore.privsep("name", root="/var/chroot/kore", runas="_kore")
   1122 ```
   1123 
   1124 ### Description
   1125 
   1126 Configuration privilege separation for Kore processes.
   1127 
   1128 This allows you to set the root directory of each process and what
   1129 user it will run as.
   1130 
   1131 ### Returns
   1132 
   1133 Nothing
   1134 
   1135 ### Example
   1136 
   1137 ```python
   1138 kore.privsep("acme", root="/var/chroot/acme", runas="acme")
   1139 kore.privsep("worker", root="/var/chroot/kore", runas="kore")
   1140 kore.privsep("keymgr", root="/var/chroot/keymgr", runas="keymgr")
   1141 ```
   1142 ---
   1143 
   1144 # HTTP {#httpmodule}
   1145 
   1146 Like the C API Kore will pass an http\_request data structure to your
   1147 Python page handler. This data structure is of type **kore.http\_request**.
   1148 
   1149 ## Constants {#httpmoduleconstants}
   1150 
   1151 * HTTP\_METHOD\_GET
   1152 * HTTP\_METHOD\_PUT
   1153 * HTTP\_METHOD\_HEAD
   1154 * HTTP\_METHOD\_POST
   1155 * HTTP\_METHOD\_DELETE
   1156 * HTTP\_METHOD\_OPTIONS
   1157 * HTTP\_METHOD\_PATCH
   1158 
   1159 ## Getters {#httpmodulegetters}
   1160 
   1161 * host - The domain as a unicode string.
   1162 * agent - The user agent as a unicode string.
   1163 * path - The requested path as a unicode string.
   1164 * body - The entire incoming HTTP body as a PyBuffer.
   1165 * method - The requested method as a PyLong. (kore.HTTP\_METHOD\_GET, etc).
   1166 * body\_path - The path to the HTTP body on disk (if enabled).
   1167 * connection - The underlying client connection as a **kore.connection** object.
   1168 
   1169 ## Functions {#httpmodulefunctions}
   1170 
   1171 ---
   1172 
   1173 # cookie {#cookie}
   1174 
   1175 ### Synopsis
   1176 
   1177 ```python
   1178 cookie = req.cookie(name)
   1179 ```
   1180 
   1181 ### Description
   1182 
   1183 Returns the cookie value for a given name.
   1184 
   1185 | Parameter | Description |
   1186 | --- | --- |
   1187 | name | The name of the cookie to lookup. |
   1188 
   1189 ### Returns
   1190 
   1191 Returns the value of the cookie as a unicode string or None if not found.
   1192 
   1193 ### Example
   1194 
   1195 ```python
   1196 def handler(req):
   1197 	cookie = req.cookie("my_session")
   1198 	if cookie != None:
   1199 		# use cookie value to do things.
   1200 ```
   1201 
   1202 ---
   1203 
   1204 # response {#response}
   1205 
   1206 ### Synopsis
   1207 
   1208 ```python
   1209 req.response(status, body)
   1210 ```
   1211 
   1212 ### Description
   1213 
   1214 Creates an HTTP response for the given HTTP request.
   1215 
   1216 | Parameter | Description |
   1217 | --- | --- |
   1218 | status | The HTTP status code to include in the response. |
   1219 | body | The HTTP body to be included in the response, this must be a binary buffer. |
   1220 
   1221 ### Returns
   1222 
   1223 Nothing
   1224 
   1225 ### Example
   1226 
   1227 ```python
   1228 def handler(req):
   1229 	req.response(200, b'ok')
   1230 ```
   1231 
   1232 ---
   1233 
   1234 # argument {#argument}
   1235 
   1236 ### Synopsis
   1237 
   1238 ```python
   1239 value = req.argument(name)
   1240 ```
   1241 
   1242 ### Description
   1243 
   1244 Looks up an HTTP parameter that was previously validated via a Kore
   1245 params block in the configuration.
   1246 
   1247 | Parameter | Description |
   1248 | --- | --- |
   1249 | name | The name of the parameter to lookup. |
   1250 
   1251 ### Returns
   1252 
   1253 The parameter as a unicode string or None if it was not found.
   1254 
   1255 ### Example
   1256 
   1257 ```python
   1258 def handler(req):
   1259 	id = req.argument("id")
   1260 	if id != None:
   1261 		# got an id from somewhere
   1262 ```
   1263 
   1264 ---
   1265 
   1266 # body\_read {#bodyread}
   1267 
   1268 ### Synopsis
   1269 
   1270 ```python
   1271 length, chunk = req.body_read(length)
   1272 ```
   1273 
   1274 ### Description
   1275 
   1276 Reads up to *length* bytes from the HTTP body and returns the actual
   1277 bytes read and data in a tuple.
   1278 
   1279 A returned length of 0 bytes indicates the end of the HTTP body.
   1280 
   1281 A RuntimeError exception is thrown if the *length* parameter is greater than 1024.
   1282 
   1283 | Parameter | Description |
   1284 | --- | --- |
   1285 | length | The number of bytes to read. |
   1286 
   1287 ### Returns
   1288 
   1289 The length and data read.
   1290 
   1291 ### Example
   1292 
   1293 ```python
   1294 def handler(req):
   1295 	if req.method == kore.HTTP_METHOD_POST:
   1296 		try
   1297 			length, body = req.body_read(1024)
   1298 			# do stuff with the body.
   1299 		except:
   1300 			kore.log(kore.LOG_INFO, "some error occurred")
   1301 			req.response(500, b'')
   1302 ```
   1303 
   1304 ---
   1305 
   1306 # file\_lookup {#filelookup}
   1307 
   1308 ### Synopsis
   1309 
   1310 ```python
   1311 file = req.file_lookup(name)
   1312 ```
   1313 
   1314 ### Description
   1315 
   1316 Lookup an uploaded file (via multipart/form-data).
   1317 
   1318 | Parameter | Description |
   1319 | --- | --- |
   1320 | name | The name of the file that was uploaded. |
   1321 
   1322 ### Returns
   1323 
   1324 A **kore.http\_file** object that can be used to read data from.
   1325 
   1326 ### Example
   1327 
   1328 ```python
   1329 def handler(req):
   1330 	if req.method == kore.HTTP_METHOD_POST:
   1331 		req.populate_multi()
   1332 		try
   1333 			file = req.file_lookup("myfile")
   1334 			length, data = file.read(1024)
   1335 			# do stuff with the data .
   1336 		except:
   1337 			kore.log(kore.LOG_INFO, "some error occurred")
   1338 			req.response(500, b'')
   1339 ```
   1340 
   1341 ---
   1342 
   1343 # populate\_get {#populateget}
   1344 
   1345 ### Synopsis
   1346 
   1347 ```python
   1348 req.populate_get()
   1349 ```
   1350 
   1351 ### Description
   1352 
   1353 Instructs Kore to go ahead and parse the incoming querystring and validate
   1354 parameters according to the configured params {} blocks in the configuration.
   1355 
   1356 ### Returns
   1357 
   1358 Nothing
   1359 
   1360 ---
   1361 
   1362 # populate\_post {#populatepost}
   1363 
   1364 ### Synopsis
   1365 
   1366 ```python
   1367 req.populate_post()
   1368 ```
   1369 
   1370 ### Description
   1371 
   1372 Instructs Kore to go ahead and parse the incoming POST data which is of
   1373 content-type *application/x-www-form-urlencoded*  and validate
   1374 parameters according to the configured params {} blocks in the configuration.
   1375 
   1376 ### Returns
   1377 
   1378 Nothing
   1379 
   1380 ---
   1381 
   1382 # populate\_multipart {#populatemultipart}
   1383 
   1384 ### Synopsis
   1385 
   1386 ```python
   1387 req.populate_multipart()
   1388 ```
   1389 
   1390 ### Description
   1391 
   1392 Instructs Kore to go ahead and parse the incoming body as content-type
   1393 multipart/form-data and validate parameters according to the configured
   1394 params {} blocks in the configuration.
   1395 
   1396 ### Returns
   1397 
   1398 Nothing
   1399 
   1400 ---
   1401 
   1402 # populate\_cookies {#populatecookies}
   1403 
   1404 ### Synopsis
   1405 
   1406 ```python
   1407 req.populate_cookies()
   1408 ```
   1409 
   1410 ### Description
   1411 
   1412 Instructs Kore to go ahead and parse the incoming cookie header (if any).
   1413 
   1414 ### Returns
   1415 
   1416 Nothing
   1417 
   1418 ---
   1419 
   1420 # request\_header {#requestheader}
   1421 
   1422 ### Synopsis
   1423 
   1424 ```python
   1425 value = req.request_header(name)
   1426 ```
   1427 
   1428 ### Description
   1429 
   1430 Finds the incoming request header by name and returns it.
   1431 
   1432 | Parameter | Description |
   1433 | --- | --- |
   1434 | name | The name of the header to lookup. |
   1435 
   1436 ### Returns
   1437 
   1438 The value of the header as a unicode string or None if the header was not present.
   1439 
   1440 ### Example
   1441 
   1442 ```python
   1443 def myhandler(req):
   1444 	xrequest = req.request_header("x-request")
   1445 	if xrequest != None:
   1446 		req.response_header("x-response", xrequest)
   1447 
   1448 	req.response(200, b'hello world')
   1449 ```
   1450 
   1451 ---
   1452 
   1453 # response\_header {#responseheader}
   1454 
   1455 ### Synopsis
   1456 
   1457 ```python
   1458 req.response_header(name, value)
   1459 ```
   1460 
   1461 ### Description
   1462 
   1463 Adds the given header to the response that will be sent by req.response().
   1464 
   1465 | Parameter | Description |
   1466 | --- | --- |
   1467 | name | The name of the header that will be added. |
   1468 | value | The value of the header that will be added. |
   1469 
   1470 ### Returns
   1471 
   1472 Nothing
   1473 
   1474 ### Example
   1475 
   1476 ```python
   1477 def myhandler(req):
   1478 	xrequest = req.request_header("x-request")
   1479 	if xrequest != None:
   1480 		req.response_header("x-response", xrequest)
   1481 
   1482 	req.response(200, b'hello world')
   1483 ```
   1484 
   1485 ---
   1486 
   1487 # websocket\_handshake {#websockethandshake}
   1488 
   1489 ### Synopsis
   1490 
   1491 ```python
   1492 req.websocket_handshake(onconnect, onmsg, ondisconnect)
   1493 ```
   1494 
   1495 ### Description
   1496 
   1497 Adds the given header to the response that will be sent by req.response().
   1498 
   1499 | Parameter | Description |
   1500 | --- | --- |
   1501 | onconnect | The name of the function to be called when a new websocket client is connected. |
   1502 | onmsg | The name of the function to be called when a websocket message arrives. |
   1503 | ondisconnect | The name of the function to be called when a new websocket client is removed. |
   1504 
   1505 ### Returns
   1506 
   1507 Nothing
   1508 
   1509 ### Example
   1510 
   1511 ```python
   1512 def onconnect(c):
   1513 	kore.log(kore.LOG_INFO, "%s: connected" % c)
   1514 
   1515 def onmessage(c, op, data):
   1516 	# data from c arrived
   1517 	# op is the websocket op, WEBSOCKET_OP_TEXT, WEBSOCKET_OP_BINARY
   1518 	# data is the data that arrived
   1519 
   1520 def ondisconnect(c):
   1521 	kore.log(kore.LOG_INFO, "%s: disconnected" % c)
   1522 
   1523 def ws_connect(req):
   1524 	req.websocket_handshake("onconnect", "onmsg", "ondisconnect")
   1525 ```
   1526 
   1527 ---
   1528 
   1529 
   1530 # Async/await {#async}
   1531 
   1532 Kore exposes several functions that can be awaited upon allowing you to
   1533 write concurrent page handlers without any callbacks.
   1534 
   1535 Kore currently supports:
   1536 
   1537   * [Sockets](#asyncsocket)
   1538   * [Locks](#asynclock)
   1539   * [Queues](#asyncqueue)
   1540   * [Processes](#asyncproc)
   1541 
   1542 For example code covering all asynchronous features, please see the
   1543 [python-async](https://github.com/jorisvink/kore/tree/master/examples/python-async) example.
   1544 
   1545 You may choose to create new coroutines using <a href="#taskcreate">task_create</a> or await several coroutines using <a href="#gather">gather</a>.
   1546 
   1547 ## Asynchronous sockets {#asyncsocket}
   1548 
   1549 You can use an existing Python socket object and wrap it inside of a Kore
   1550 socket. When you have a wrapped socket you can connect/accept, send or recv
   1551 asynchronously.
   1552 
   1553 * [recv](#socketrecv)
   1554 * [recvfrom](#socketrecvfrom)
   1555 * [send](#socketsend)
   1556 * [sendto](#socketsendto)
   1557 * [accept](#socketaccept)
   1558 * [connect](#socketconnect)
   1559 * [close](#socketclose)
   1560 
   1561 Example:
   1562 
   1563 ```python
   1564 import kore
   1565 import socket
   1566 
   1567 async def page(req):
   1568     sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM |
   1569                                          socket.SOCK_NONBLOCK)
   1570 
   1571     # Wrap the socket in a Kore object.
   1572     ksock = kore.socket_wrap(sock)
   1573 
   1574     # Connect and send some data.
   1575     await ksock.connect("127.0.0.1", 3332)
   1576     await ksock.send("hello world")
   1577 
   1578     # Read a response.
   1579     response = await ksock.recv(1024)
   1580 
   1581     ksock.close()
   1582     sock.close()
   1583 ```
   1584 
   1585 ---
   1586 
   1587 ### sock.recv {#socketrecv}
   1588 
   1589 ### Synopsis
   1590 
   1591 ```python
   1592 data = await sock.recv(maxlen, timeout)
   1593 ```
   1594 
   1595 ### Description
   1596 
   1597 Reads up to **maxlen** bytes from the socket. The optional **timeout** argument
   1598 will throw a TimeoutError exception in case the timeout is hit before data is
   1599 read from the socket. If no timeout argument is specified, the call will wait
   1600 until data is available.
   1601 
   1602 
   1603 | Parameter | Description |
   1604 | --- | --- |
   1605 | maxlen | Maximum number of bytes to be read. |
   1606 | timeout | Optional timeout in milliseconds. |
   1607 
   1608 ### Returns
   1609 
   1610 The bytes read as a byte object or None on EOF.
   1611 
   1612 ### Example
   1613 
   1614 ```python
   1615 data = await sock.recv(1024)
   1616 if data is None:
   1617     printf("eof!")
   1618 else:
   1619     print("received %s" % data)
   1620 
   1621 # Use optional timeout argument
   1622 try:
   1623     data = await sock.recv(1024, 1000)
   1624 except TimeoutError as e:
   1625     print("timed out reading (%s)" % e)
   1626 ```
   1627 
   1628 ---
   1629 
   1630 ### sock.recvfrom {#socketrecvfrom}
   1631 
   1632 ### Synopsis
   1633 
   1634 ```python
   1635 tuple = await sock.recvfrom(maxlen)
   1636 ```
   1637 
   1638 ### Description
   1639 
   1640 Reads up to **maxlen** bytes from the socket while returning the source
   1641 and data.
   1642 
   1643 | Parameter | Description |
   1644 | --- | --- |
   1645 | maxlen | Maximum number of bytes to be read. |
   1646 
   1647 ### Returns
   1648 
   1649 A tuple of (address, port, data) for AF\_INET,
   1650 A tuple of (address, data) for AF\_UNIX.
   1651 
   1652 None on EOF.
   1653 
   1654 ### Example
   1655 
   1656 ```python
   1657 ip, port, data = await sock.recvfrom(1024)
   1658 if data is None:
   1659     printf("eof!")
   1660 else:
   1661     await sock.sendto(ip, port, data)
   1662 ```
   1663 
   1664 ---
   1665 
   1666 ### sock.recvmsg {#socketrecvmsg}
   1667 
   1668 ### Synopsis
   1669 
   1670 ```python
   1671 data, ancdata = await sock.recvmsg(maxlen, timeout)
   1672 ```
   1673 
   1674 ### Description
   1675 
   1676 Reads up to **maxlen** bytes from the socket. The optional **timeout** argument
   1677 will throw a TimeoutError exception in case the timeout is hit before data is
   1678 read from the socket. If no timeout argument is specified, the call will wait
   1679 until data is available.
   1680 
   1681 The return ancillary data is in a list, with one tuple of 3 per entry:
   1682 
   1683 (cmsg_level, cmsg_type, cmsg_data)
   1684 
   1685 | Parameter | Description |
   1686 
   1687 | --- | --- |
   1688 | maxlen | Maximum number of bytes to be read. |
   1689 | timeout | Optional timeout in milliseconds. |
   1690 
   1691 ### Returns
   1692 
   1693 The bytes read as a byte object, the ancelliry data as a list or None on EOF.
   1694 
   1695 ### Example
   1696 
   1697 ```python
   1698 data, ancdata = await sock.recvmsg(1024)
   1699 if data is None:
   1700     printf("eof!")
   1701 else:
   1702     for cmsg_level, cmsg_type, cmsg_data in ancdata:
   1703         # handle
   1704 ```
   1705 
   1706 ---
   1707 
   1708 ### sock.send {#socketsend}
   1709 
   1710 ### Synopsis
   1711 
   1712 ```python
   1713 await sock.send(data)
   1714 ```
   1715 
   1716 ### Description
   1717 
   1718 Sends the given data over the socket.
   1719 
   1720 | Parameter | Description |
   1721 | --- | --- |
   1722 | data | The data to be sent (as bytes). |
   1723 
   1724 ### Returns
   1725 
   1726 Nothing. In case the peer closes the socket before all data is written
   1727 a RuntimeException is thrown.
   1728 
   1729 ### Example
   1730 
   1731 ```python
   1732 # Will return when all bytes are sent.
   1733 await sock.send("Hello world")
   1734 ```
   1735 
   1736 ---
   1737 
   1738 ### sock.sendto {#socketsendto}
   1739 
   1740 ### Synopsis
   1741 
   1742 ```python
   1743 await sock.sendto(address, port, data)
   1744 ```
   1745 
   1746 ### Description
   1747 
   1748 Sends the given data over the socket to the specified destination.
   1749 
   1750 for AF\_INET:
   1751 
   1752 | Parameter | Description |
   1753 | --- | --- |
   1754 | address | The destination IP address. |
   1755 | port | The destination port. |
   1756 | data | The data to be sent (as bytes). |
   1757 
   1758 For AF\_UNIX:
   1759 
   1760 | Parameter | Description |
   1761 | --- | --- |
   1762 | address | The destination address path. |
   1763 | data | The data to be sent (as bytes). |
   1764 
   1765 ### Returns
   1766 
   1767 Nothing. In case the peer closes the socket before all data is written
   1768 a RuntimeException is thrown.
   1769 
   1770 ### Example
   1771 
   1772 ```python
   1773 # AF_INET, will return when all bytes are sent.
   1774 await sock.sendto("127.0.0.1", "3311", "Hello world")
   1775 
   1776 # AF_UNIX, will return when all bytes are sent.
   1777 await sock.sendto("/tmp/service.sock", "Hello world")
   1778 ```
   1779 
   1780 ---
   1781 
   1782 ### sock.accept {#socketaccept}
   1783 
   1784 ### Synopsis
   1785 
   1786 ```python
   1787 await sock.accept()
   1788 ```
   1789 
   1790 ### Description
   1791 
   1792 Accepts a new connection on the socket.
   1793 
   1794 ### Returns
   1795 
   1796 A kore.socket data object that can be used to send/recv data on.
   1797 
   1798 ### Example
   1799 
   1800 ```python
   1801 conn = await sock.accept()
   1802 await conn.send("welcome")
   1803 conn.close()
   1804 ```
   1805 
   1806 ---
   1807 
   1808 ### sock.connect {##socketconnect}
   1809 
   1810 ### Synopsis
   1811 
   1812 ```python
   1813 await sock.connect()
   1814 ```
   1815 
   1816 ### Description
   1817 
   1818 Connects to a peer.
   1819 
   1820 ### Returns
   1821 
   1822 Nothing.
   1823 
   1824 ### Example
   1825 
   1826 ```python
   1827 # AF_INET socket.
   1828 await sock.connect("127.0.0.1", 8888)
   1829 data = await sock.recv(1024)
   1830 sock.close()
   1831 
   1832 # AF_UNIX socket.
   1833 await sock.connect("/var/run/socket.sock")
   1834 data = await sock.recv(1024)
   1835 sock.close()
   1836 
   1837 ```
   1838 
   1839 ---
   1840 
   1841 ### sock.close {#socketclose}
   1842 
   1843 ### Synopsis
   1844 
   1845 ```python
   1846 sock.close()
   1847 ```
   1848 
   1849 ### Description
   1850 
   1851 Closes the underlying socket. If the socket was created from an
   1852 underlying Python socket, it is not closed.
   1853 
   1854 ### Returns
   1855 
   1856 Nothing.
   1857 
   1858 ---
   1859 
   1860 ## Locks {#asynclock}
   1861 
   1862 Kore provides a locking mechanism where multiple coroutines can wait
   1863 upon a lock in a non-blocking way. This allows synchronization between
   1864 coroutines in a straight forward way.
   1865 
   1866 A lock is created by calling **kore.lock()**.
   1867 
   1868 An coroutine can use the lock with the Python "async with" syntax.
   1869 
   1870 Example:
   1871 
   1872 ```python
   1873 # Create the lock
   1874 lock = kore.lock()
   1875 
   1876 async def request(req):
   1877 	# Only allow one request at a time to this handler.
   1878 	async with lock:
   1879 		# do things
   1880 		req.response(200, b'ok')
   1881 ```
   1882 
   1883 ---
   1884 
   1885 ## Queues {#asyncqueue}
   1886 
   1887 Kore provides a queue system that allows objects to be sent back and forth
   1888 between coroutines in a non-blocking fashion.
   1889 
   1890 The queue is a FIFO queue.
   1891 
   1892 * [push](#queuepush)
   1893 * [pop](#queuepop)
   1894 * [popnow](#queuepopnow)
   1895 
   1896 ---
   1897 
   1898 ### queue.push {#queuepush}
   1899 
   1900 ### Synopsis
   1901 
   1902 ```python
   1903 queue.push(object)
   1904 ```
   1905 
   1906 ### Description
   1907 
   1908 Pushes the given **object** onto the queue. The coroutine that waited first
   1909 on the queue using **pop** will be woken up.
   1910 
   1911 | Parameter | Description |
   1912 | --- | --- |
   1913 | object | The object to be pushed onto the queue. |
   1914 
   1915 ### Returns
   1916 
   1917 Nothing.
   1918 
   1919 ### Example
   1920 
   1921 ```python
   1922 queue = kore.queue()
   1923 
   1924 d = {
   1925     "foo": "bar"
   1926 }
   1927 
   1928 queue.push(d)
   1929 ```
   1930 
   1931 ---
   1932 
   1933 ### queue.pop {#queuepop}
   1934 
   1935 ### Synopsis
   1936 
   1937 ```python
   1938 object = await queue.pop()
   1939 ```
   1940 
   1941 ### Description
   1942 
   1943 Waits for an object to be pushed onto the queue and will return that object.
   1944 
   1945 ### Returns
   1946 
   1947 The object that was received.
   1948 
   1949 ### Example
   1950 
   1951 ```python
   1952 d = await queue.pop()
   1953 ```
   1954 
   1955 ---
   1956 
   1957 ### queue.popnow {#queuepopnow}
   1958 
   1959 ### Synopsis
   1960 
   1961 ```python
   1962 object = queue.popnow()
   1963 ```
   1964 
   1965 ### Description
   1966 
   1967 Attempts to pop an object from a queue immediately.
   1968 
   1969 ### Returns
   1970 
   1971 A popped object from the queue or None if the queue was empty.
   1972 
   1973 ### Example
   1974 
   1975 ```python
   1976 d = queue.popnow()
   1977 if not d:
   1978 	continue
   1979 ```
   1980 
   1981 ---
   1982 
   1983 ## Asynchronous processes {#asyncproc}
   1984 
   1985 For a more detailed example, see [this](https://git.kore.io/kore/file/examples/python-async/src/async_process.py) source file.
   1986 
   1987 Or see the [kore.proc](https://docs.kore.io/4.1.0/api/python.html#proc) description.
   1988 
   1989 * [kill](#prockill)
   1990 * [reap](#procreap)
   1991 * [recv](#procrecv)
   1992 * [send](#procsend)
   1993 * [close\_stdin](#procclosestdin)
   1994 
   1995 ---
   1996 
   1997 ### proc.kill {#prockill}
   1998 
   1999 ### Synopsis
   2000 
   2001 ```python
   2002 proc.kill()
   2003 ```
   2004 
   2005 ### Description
   2006 
   2007 Sends an immediate SIGKILL to the process.
   2008 
   2009 ### Returns
   2010 
   2011 Nothing
   2012 
   2013 ---
   2014 
   2015 ### proc.reap {#procreap}
   2016 
   2017 ### Synopsis
   2018 
   2019 ```python
   2020 retcode = proc.reap()
   2021 ```
   2022 
   2023 ### Description
   2024 
   2025 Reaps the process and captures its exit code as the return value.
   2026 
   2027 ### Returns
   2028 
   2029 The process exit code.
   2030 
   2031 ---
   2032 
   2033 ### proc.recv {#procrecv}
   2034 
   2035 ### Synopsis
   2036 
   2037 ```python
   2038 data = await proc.recv(1024)
   2039 ```
   2040 
   2041 ### Description
   2042 
   2043 Reads up to **maxlen** bytes from the stdout pipe of the process.
   2044 
   2045 | Parameter | Description |
   2046 | --- | --- |
   2047 | maxlen | Maximum number of bytes to be read. |
   2048 
   2049 ### Returns
   2050 
   2051 The bytes read as a byte object or None on EOF.
   2052 
   2053 ---
   2054 
   2055 ### proc.send {#procsend}
   2056 
   2057 ### Synopsis
   2058 
   2059 ```python
   2060 await proc.send(data)
   2061 ```
   2062 
   2063 ### Description
   2064 
   2065 Sends the given data to the process its stdin.
   2066 
   2067 | Parameter | Description |
   2068 | --- | --- |
   2069 | data | The data to be sent (as bytes). |
   2070 
   2071 ### Returns
   2072 
   2073 Nothing. In case the process closes its stdin before all data is written
   2074 a RuntimeException is thrown.
   2075 
   2076 ---
   2077 
   2078 ### proc.close\_stdin {#procclosestdin}
   2079 
   2080 ### Synopsis
   2081 
   2082 ```python
   2083 proc.close_stdin()
   2084 ```
   2085 
   2086 ### Description
   2087 
   2088 Closes the write pipe to the process, making the process see EOF on stdin.
   2089 
   2090 ### Returns
   2091 
   2092 Nothing.
   2093 
   2094 ---
   2095