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 (42750B)



      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 | maxlen | Maximum number of bytes to be read. |
   1688 | timeout | Optional timeout in milliseconds. |
   1689 
   1690 ### Returns
   1691 
   1692 The bytes read as a byte object, the ancelliry data as a list or None on EOF.
   1693 
   1694 ### Example
   1695 
   1696 ```python
   1697 data, ancdata = await sock.recvmsg(1024)
   1698 if data is None:
   1699     printf("eof!")
   1700 else:
   1701     for cmsg_level, cmsg_type, cmsg_data in ancdata:
   1702         # handle
   1703 ```
   1704 
   1705 ---
   1706 
   1707 ### sock.send {#socketsend}
   1708 
   1709 ### Synopsis
   1710 
   1711 ```python
   1712 await sock.send(data)
   1713 ```
   1714 
   1715 ### Description
   1716 
   1717 Sends the given data over the socket.
   1718 
   1719 | Parameter | Description |
   1720 | --- | --- |
   1721 | data | The data to be sent (as bytes). |
   1722 
   1723 ### Returns
   1724 
   1725 Nothing. In case the peer closes the socket before all data is written
   1726 a RuntimeException is thrown.
   1727 
   1728 ### Example
   1729 
   1730 ```python
   1731 # Will return when all bytes are sent.
   1732 await sock.send("Hello world")
   1733 ```
   1734 
   1735 ---
   1736 
   1737 ### sock.sendto {#socketsendto}
   1738 
   1739 ### Synopsis
   1740 
   1741 ```python
   1742 await sock.sendto(address, port, data)
   1743 ```
   1744 
   1745 ### Description
   1746 
   1747 Sends the given data over the socket to the specified destination.
   1748 
   1749 for AF\_INET:
   1750 
   1751 | Parameter | Description |
   1752 | --- | --- |
   1753 | address | The destination IP address. |
   1754 | port | The destination port. |
   1755 | data | The data to be sent (as bytes). |
   1756 
   1757 For AF\_UNIX:
   1758 
   1759 | Parameter | Description |
   1760 | --- | --- |
   1761 | address | The destination address path. |
   1762 | data | The data to be sent (as bytes). |
   1763 
   1764 ### Returns
   1765 
   1766 Nothing. In case the peer closes the socket before all data is written
   1767 a RuntimeException is thrown.
   1768 
   1769 ### Example
   1770 
   1771 ```python
   1772 # AF_INET, will return when all bytes are sent.
   1773 await sock.sendto("127.0.0.1", "3311", "Hello world")
   1774 
   1775 # AF_UNIX, will return when all bytes are sent.
   1776 await sock.sendto("/tmp/service.sock", "Hello world")
   1777 ```
   1778 
   1779 ---
   1780 
   1781 ### sock.accept {#socketaccept}
   1782 
   1783 ### Synopsis
   1784 
   1785 ```python
   1786 await sock.accept()
   1787 ```
   1788 
   1789 ### Description
   1790 
   1791 Accepts a new connection on the socket.
   1792 
   1793 ### Returns
   1794 
   1795 A kore.socket data object that can be used to send/recv data on.
   1796 
   1797 ### Example
   1798 
   1799 ```python
   1800 conn = await sock.accept()
   1801 await conn.send("welcome")
   1802 conn.close()
   1803 ```
   1804 
   1805 ---
   1806 
   1807 ### sock.connect {##socketconnect}
   1808 
   1809 ### Synopsis
   1810 
   1811 ```python
   1812 await sock.connect()
   1813 ```
   1814 
   1815 ### Description
   1816 
   1817 Connects to a peer.
   1818 
   1819 ### Returns
   1820 
   1821 Nothing.
   1822 
   1823 ### Example
   1824 
   1825 ```python
   1826 # AF_INET socket.
   1827 await sock.connect("127.0.0.1", 8888)
   1828 data = await sock.recv(1024)
   1829 sock.close()
   1830 
   1831 # AF_UNIX socket.
   1832 await sock.connect("/var/run/socket.sock")
   1833 data = await sock.recv(1024)
   1834 sock.close()
   1835 
   1836 ```
   1837 
   1838 ---
   1839 
   1840 ### sock.close {#socketclose}
   1841 
   1842 ### Synopsis
   1843 
   1844 ```python
   1845 sock.close()
   1846 ```
   1847 
   1848 ### Description
   1849 
   1850 Closes the underlying socket. If the socket was created from an
   1851 underlying Python socket, it is not closed.
   1852 
   1853 ### Returns
   1854 
   1855 Nothing.
   1856 
   1857 ---
   1858 
   1859 ## Locks {#asynclock}
   1860 
   1861 Kore provides a locking mechanism where multiple coroutines can wait
   1862 upon a lock in a non-blocking way. This allows synchronization between
   1863 coroutines in a straight forward way.
   1864 
   1865 A lock is created by calling **kore.lock()**.
   1866 
   1867 An coroutine can use the lock with the Python "async with" syntax.
   1868 
   1869 Example:
   1870 
   1871 ```python
   1872 # Create the lock
   1873 lock = kore.lock()
   1874 
   1875 async def request(req):
   1876 	# Only allow one request at a time to this handler.
   1877 	async with lock:
   1878 		# do things
   1879 		req.response(200, b'ok')
   1880 ```
   1881 
   1882 ---
   1883 
   1884 ## Queues {#asyncqueue}
   1885 
   1886 Kore provides a queue system that allows objects to be sent back and forth
   1887 between coroutines in a non-blocking fashion.
   1888 
   1889 The queue is a FIFO queue.
   1890 
   1891 * [push](#queuepush)
   1892 * [pop](#queuepop)
   1893 * [popnow](#queuepopnow)
   1894 
   1895 ---
   1896 
   1897 ### queue.push {#queuepush}
   1898 
   1899 ### Synopsis
   1900 
   1901 ```python
   1902 queue.push(object)
   1903 ```
   1904 
   1905 ### Description
   1906 
   1907 Pushes the given **object** onto the queue. The coroutine that waited first
   1908 on the queue using **pop** will be woken up.
   1909 
   1910 | Parameter | Description |
   1911 | --- | --- |
   1912 | object | The object to be pushed onto the queue. |
   1913 
   1914 ### Returns
   1915 
   1916 Nothing.
   1917 
   1918 ### Example
   1919 
   1920 ```python
   1921 queue = kore.queue()
   1922 
   1923 d = {
   1924     "foo": "bar"
   1925 }
   1926 
   1927 queue.push(d)
   1928 ```
   1929 
   1930 ---
   1931 
   1932 ### queue.pop {#queuepop}
   1933 
   1934 ### Synopsis
   1935 
   1936 ```python
   1937 object = await queue.pop()
   1938 ```
   1939 
   1940 ### Description
   1941 
   1942 Waits for an object to be pushed onto the queue and will return that object.
   1943 
   1944 ### Returns
   1945 
   1946 The object that was received.
   1947 
   1948 ### Example
   1949 
   1950 ```python
   1951 d = await queue.pop()
   1952 ```
   1953 
   1954 ---
   1955 
   1956 ### queue.popnow {#queuepopnow}
   1957 
   1958 ### Synopsis
   1959 
   1960 ```python
   1961 object = queue.popnow()
   1962 ```
   1963 
   1964 ### Description
   1965 
   1966 Attempts to pop an object from a queue immediately.
   1967 
   1968 ### Returns
   1969 
   1970 A popped object from the queue or None if the queue was empty.
   1971 
   1972 ### Example
   1973 
   1974 ```python
   1975 d = queue.popnow()
   1976 if not d:
   1977 	continue
   1978 ```
   1979 
   1980 ---
   1981 
   1982 ## Asynchronous processes {#asyncproc}
   1983 
   1984 For a more detailed example, see [this](https://git.kore.io/kore/file/examples/python-async/src/async_process.py) source file.
   1985 
   1986 Or see the [kore.proc](https://docs.kore.io/4.1.0/api/python.html#proc) description.
   1987 
   1988 * [kill](#prockill)
   1989 * [reap](#procreap)
   1990 * [recv](#procrecv)
   1991 * [send](#procsend)
   1992 * [close\_stdin](#procclosestdin)
   1993 
   1994 ---
   1995 
   1996 ### proc.kill {#prockill}
   1997 
   1998 ### Synopsis
   1999 
   2000 ```python
   2001 proc.kill()
   2002 ```
   2003 
   2004 ### Description
   2005 
   2006 Sends an immediate SIGKILL to the process.
   2007 
   2008 ### Returns
   2009 
   2010 Nothing
   2011 
   2012 ---
   2013 
   2014 ### proc.reap {#procreap}
   2015 
   2016 ### Synopsis
   2017 
   2018 ```python
   2019 retcode = proc.reap()
   2020 ```
   2021 
   2022 ### Description
   2023 
   2024 Reaps the process and captures its exit code as the return value.
   2025 
   2026 ### Returns
   2027 
   2028 The process exit code.
   2029 
   2030 ---
   2031 
   2032 ### proc.recv {#procrecv}
   2033 
   2034 ### Synopsis
   2035 
   2036 ```python
   2037 data = await proc.recv(1024)
   2038 ```
   2039 
   2040 ### Description
   2041 
   2042 Reads up to **maxlen** bytes from the stdout pipe of the process.
   2043 
   2044 | Parameter | Description |
   2045 | --- | --- |
   2046 | maxlen | Maximum number of bytes to be read. |
   2047 
   2048 ### Returns
   2049 
   2050 The bytes read as a byte object or None on EOF.
   2051 
   2052 ---
   2053 
   2054 ### proc.send {#procsend}
   2055 
   2056 ### Synopsis
   2057 
   2058 ```python
   2059 await proc.send(data)
   2060 ```
   2061 
   2062 ### Description
   2063 
   2064 Sends the given data to the process its stdin.
   2065 
   2066 | Parameter | Description |
   2067 | --- | --- |
   2068 | data | The data to be sent (as bytes). |
   2069 
   2070 ### Returns
   2071 
   2072 Nothing. In case the process closes its stdin before all data is written
   2073 a RuntimeException is thrown.
   2074 
   2075 ---
   2076 
   2077 ### proc.close\_stdin {#procclosestdin}
   2078 
   2079 ### Synopsis
   2080 
   2081 ```python
   2082 proc.close_stdin()
   2083 ```
   2084 
   2085 ### Description
   2086 
   2087 Closes the write pipe to the process, making the process see EOF on stdin.
   2088 
   2089 ### Returns
   2090 
   2091 Nothing.
   2092 
   2093 ---
   2094