Kuyruk Documentation. Release 0. Cenk Altı

Kuyruk Documentation Release 0 Cenk Altı Mar 07, 2018

Contents 1 About Kuyruk 3 2 User s Guide 5 3 API Reference 17 4 Indices and tables 21 Python Module Index 23 i

ii

Welcome to Kuyruk s documentation. This documentation covers the usage of the library and describes how to run workers. Contents 1

2 Contents

CHAPTER 1 About Kuyruk Kuyruk is a simple and easy way of distributing tasks to run on servers. It uses RabbitMQ as message broker and depends on amqp which is a pure-python RabbitMQ client library. Compatible with Python 3.5+. All design decisions is based on simplicity. Speed is not first priority. Kuyruk only supports RabbitMQ and does not plan to support any other backend. Kuyruk requires no change in client code other than adding a decorator on top of a function in order to convert it to a Task. Also, sensible defaults have been set for configuration options and can be run without configuring during the development of your application. Kuyruk is designed for long running mission critical jobs. For this reason Kuyruk sends acknowledgement only after the task is fully processed. 3

4 Chapter 1. About Kuyruk

CHAPTER 2 User s Guide 2.1 Getting Started Running a function in background requires only few steps with Kuyruk. This tutorial assumes that you have a running RabbitMQ server on localhost with default configuration. Following files and commands are in example directory for convenience. 2.1.1 Installing Kuyruk is available on PyPI. You can install it via pip. $ pip install kuyruk 2.1.2 Defining Tasks Instantiate a Kuyruk object and put a task() decorator on top of your function. This will convert your function into a Task object. # tasks.py from kuyruk import Kuyruk kuyruk = Kuyruk() @kuyruk.task() def echo(message): print message You can specify some options when defining task. See task() for details. 5

2.1.3 Sending the Task to RabbitMQ When you call the Task object, Kuyruk will serialize the task as JSON and will send it to a queue on RabbitMQ instead of running it. import tasks tasks.echo("hello, World!") 2.1.4 Running a Worker Run the following command to process tasks in default queue. $ kuyruk --app tasks.kuyruk worker 2.2 Worker Worker processes tasks from a queue. 2.2.1 Usage $ kuyruk --app <path.to.kuyruk.instance> --queue <queue_name> If queue_name is not given default queue name( kuyruk ) is used. Example: $ kuyruk --app tasks.kuyruk --queue download_file 2.2.2 OS Signals Description of how worker processes react to OS signals. SIGINT Worker exits after completing the current task. This is the signal sent when you press CTRL-C on your keyboard. SIGTERM Worker exits after completing the current task. SIGQUIT Worker quits immediately. This is unclean shutdown. If worker is running a task it will be requeued by RabbitMQ. This is the signal sent when you press CTRL-on your keyboard. SIGUSR1 Prints stacktrace. Useful for debugging stuck tasks or seeing what the worker is doing. SIGUSR2 Discard current task and proceed to next one. Discarded task will not be requeued by RabbitMQ. SIGHUP Used internally to fail the task when connection to RabbitMQ is lost during the execution of a long running task. Do not use it. 6 Chapter 2. User s Guide

2.3 Signals Kuyruk can be extended via signals. Kuyruk has a signalling support via Blinker library. 2.3.1 Example Here is an example for clearing the SQLAlchemy s scoped_session before executing the function and commiting it after the task is executed: from kuyruk import Kuyruk from kuyruk.signals import task_prerun, task_postrun from myapp.orm import Session kuyruk = Kuyruk() @task_prerun.connect_via(kuyruk) def open_session(sender, task=none, **extra): task.session = Session() @task_postrun.connect_via(kuyruk) def close_session(sender, task=none, **extra): task.session.close() @kuyruk.task() def task_with_a_session(): session = task_with_a_session.session # Work with the session... session.commit() 2.3.2 List of Signals kuyruk.signals.task_init = <blinker.base.signal object> Sent when the task decorator is applied. Arguments: sender: Kuyruk object task: Task object kuyruk.signals.task_preapply = <blinker.base.signal object> Sent before the task is applied. Arguments: sender: Kuyruk object task: Task object args: Positional arguments to the task kwargs: Keyword arguments to the task kuyruk.signals.task_postapply = <blinker.base.signal object> Sent after the task is applied. Arguments: 2.3. Signals 7

sender: Kuyruk object task: Task object args: Positional arguments to the task kwargs: Keyword arguments to the task kuyruk.signals.task_prerun = <blinker.base.signal object> Sent before the wrapped function is executed. Arguments: sender: Kuyruk object task: Task object args: Positional arguments to the task kwargs: Keyword arguments to the task kuyruk.signals.task_postrun = <blinker.base.signal object> Sent after the wrapped function is executed. Arguments: sender: Kuyruk object task: Task object args: Positional arguments to the task kwargs: Keyword arguments to the task kuyruk.signals.task_success = <blinker.base.signal object> Sent when the wrapped function is returned. Arguments: sender: Kuyruk object task: Task object args: Positional arguments to the task kwargs: Keyword arguments to the task kuyruk.signals.task_error = <blinker.base.signal object> Sent when the wrapped function raises an exception. Arguments: sender: Kuyruk object task: Task object args: Positional arguments to the task kwargs: Keyword arguments to the task exc_info: Return value of sys.exc_info() kuyruk.signals.task_failure = <blinker.base.signal object> Sent when the task fails after all retries(if any). Arguments: sender: Kuyruk object task: Task object 8 Chapter 2. User s Guide

args: Positional arguments to the task kwargs: Keyword arguments to the task exc_info: Return value of sys.exc_info() kuyruk.signals.task_presend = <blinker.base.signal object> Sent before the task is sent to queue. Arguments: sender: Kuyruk object task: Task object args: Positional arguments to the task kwargs: Keyword arguments to the task description: dict representation of the task kuyruk.signals.task_postsend = <blinker.base.signal object> Sent after the task is sent to queue. Arguments: sender: Kuyruk object task: Task object args: Positional arguments to the task kwargs: Keyword arguments to the task description: dict representation of the task kuyruk.signals.worker_failure = <blinker.base.signal object> Sent when the task fails. Arguments: sender: Kuyruk object worker: The Worker object task: Task object args: Positional arguments to the task kwargs: Keyword arguments to the task description: dict representation of the task exc_info: Return value of sys.exc_info() kuyruk.signals.worker_init = <blinker.base.signal object> Sent when the worker is initialized. Arguments: sender: Kuyruk object worker: The Worker object kuyruk.signals.worker_start = <blinker.base.signal object> Sent when the worker is started. Arguments: sender: Kuyruk object 2.3. Signals 9

worker: The Worker object kuyruk.signals.worker_shutdown = <blinker.base.signal object> Sent when the worker shuts down. Arguments: sender: Kuyruk object worker: The Worker object 2.4 Extensions These are some extensions that adds a functionality to Kuyruk. 2.4.1 Kuyruk-Sentry https://github.com/cenkalti/kuyruk-sentry Sends exceptions in Kuyruk workers to Sentry. 2.4.2 Kuyruk-Requeue https://github.com/cenkalti/kuyruk-requeue Save failed tasks to Redis and requeue them. 2.4.3 Kuyruk-Manager https://github.com/cenkalti/kuyruk-manager See and manage Kuyruk workers.. 2.5 Changelog Here you can see the full list of changes between each Kuyruk release. 2.5.1 Version 8.5.0 Released on 25-10-2017. Added Windows support. 2.5.2 Version 8.3.0 Released on 15-04-2017. Added Kuyruk.send_tasks_to_queue method for batch sending. 10 Chapter 2. User s Guide

2.5.3 Version 8.2.0 Released on 22-02-2017. Added delay for failed and rejected taks. 2.5.4 Version 8.1.0 Released on 25-11-2016. Added RabbitMQ connection timeout values to config. 2.5.5 Version 8.0.0 Released on 23-11-2016. Removed queue key from task description dictionary. Improve error handling when closing connections and channels. 2.5.6 Version 7.0.0 Released on 01-11-2016. Removed local argument from Kuyruk.task decorator. 2.5.7 Version 6.0.0 Released on 01-11-2016. Changed WORKER_MAX_LOAD behavior. None disables the feature. Set to -1 for number of CPUs on host. Add argumens to worker command to override WORKER_MAX_LOAD and WORKER_MAX_RUN_TIME config values. Renamed ConnectionError to HeartbeatError. Removed Task.run_in_queue method. Use Task.send_to_queue with wait_result argument instead. Removed local argument from Task.send_to_queue method. Pass host="localhost" for sending to local queue. Removed local argument from worker command. If queue name ends with ".localhost" hostname will be appended to queue name. Removed deprecated Worker.queue property. Removed WORKER_LOGGING_CONFIG configuration value. Added --logging-level to worker command arguments. Removed Worker.config property. Added message_ttl argument to Task.send_to_queue method. 2.5. Changelog 11

2.5.8 Version 5.1.0 Released on 26-10-2016. Added Task.run_in_queue context manager for getting task results. 2.5.9 Version 5.0.0 Released on 19-10-2016. Removed kuyruk_host and kuyruk_local arguments from task calls. Exported Task.send_to_queue method. 2.5.10 Version 4.1.2 Released on 18-10-2016. Fixed 1 second delay after processing a task. Fixed a depreciation warning from recent version of amqp library. 2.5.11 Version 4.1.0 Released on 11-03-2016. Workers can consume tasks from multiple queues. 2.5.12 Version 4.0.7 Released on 12-02-2016. Export Task.name property for fixing a bug in kuyruk-manager. 2.5.13 Version 4.0.6 Released on 08-02-2016 Fixed a bug related with Python 2.7.11, uwsgi and setproctitle. 2.5.14 Version 2.0.0 Released on 03-12-2014. This is major rewrite of Kuyruk and it is not backwards compatible. Added Python 3 support. Replaced pika with amqp. Fixed multi-threading issues. Removed master subcommand. Removed scheduler subcommand. 12 Chapter 2. User s Guide

Removed requeue subcommand. Removed manager subcommand. Exceptions are not sent to Sentry. Failed tasks are not saved to Redis anymore. Failed tasks are retried in the same worker. Unknown keys in config are now errors. Changed some config variable names. Worker command takes Kuyruk instance instead of config file. 2.5.15 Version 1.2.1 Released on 25-08-2014. Fixed a worker startup bug happens when running workers as another user. 2.5.16 Version 1.2.0 Released on 09-06-2014. Added periodic task scheduler feature. 2.5.17 Version 1.1.0 Released on 07-06-2014. Added Task.delay() function alias for easy migration from Celery. 2.5.18 Version 1.0.0 Released on 20-05-2014. Use rpyc library for manager communication. 2.5.19 Version 0.24.3 Released on 05-03-2014. Reverted the option to give Task class from configuration. This caused master to import from user code. Added sleep after respawn_worker to prevent cpu burning. 2.5.20 Version 0.24.2 Released on 16-01-2014. Added the option to give Task class from configuration. 2.5. Changelog 13

2.5.21 Version 0.24.1 Released on 13-01-2014. Prevented close to be called on a nonexistent connection. 2.5.22 Version 0.23.3 Released on 15-09-2013. Fix the bug about freezing processes on exit. 2.5.23 Version 0.23.2 Released on 12-09-2013. Fix unclosed socket error on manager. 2.5.24 Version 0.23.0 Released on 30-08-2013. Removed InvalidCall exception type. TypeError or AttributeError is raised instead. If a kuyruk process exits with a signal, the exit code will be 0. 2.5.25 Version 0.22.1 Released on 27-08-2013. Master uses os.wait() instead of polling workers every second. 2.5.26 Version 0.22.0 Released on 25-08-2013. Use forking again instead Popen after fixing import issue. Add Quit Task button to Manager interface. 2.5.27 Version 0.21.0 Released on 17-08-2013. Drop support for Python 2.6. Switch back to subprocess module from forking. 2.5.28 Version 0.20.3 Released on 10-08-2013. Use fork() directly instead of subprocess.popen() when starting workers from master. 14 Chapter 2. User s Guide

2.5.29 Version 0.20.2 Released on 03-08-2013. First public release. 2.5. Changelog 15

16 Chapter 2. User s Guide

CHAPTER 3 API Reference 3.1 Kuyruk Class class kuyruk.kuyruk(config: kuyruk.config.config = None) None Provides task() decorator to convert a function into a Task. Provides channel() context manager for opening a new channel on the connection. Connection is opened when the first channel is created. Parameters config Must be an instance of Config. If None, default config is used. See Config for default values. channel() typing.iterator[amqp.channel.channel] Returns a new channel from a new connection as a context manager. connection() typing.iterator[amqp.connection.connection] Returns a new connection as a context manager. task(queue: str = kuyruk, **kwargs: typing.any) typing.callable Wrap functions with this decorator to convert them to tasks. After wrapping, calling the function will send a message to a queue instead of running the function. Parameters queue Queue name for the tasks. kwargs Keyword arguments will be passed to Task constructor. Returns Callable Task object wrapping the original function. 3.2 Task Class class kuyruk.task Calling a Task object serializes the task to JSON and sends it to the queue. Parameters 17

retry Retry this times before give up. The failed task will be retried in the same worker. max_run_time Maximum allowed time in seconds for task to complete. apply(*args: typing.any, **kwargs: typing.any) typing.any Called by workers to run the wrapped function. You may call it yourself if you want to run the task in current process without sending to the queue. If task has a retry property it will be retried on failure. If task has a max_run_time property the task will not be allowed to run more than that. name Full path to the task in the form of <module>.<function>. Workers find and import tasks by this path. send_to_queue(args: typing.tuple = (), kwargs: typing.dict[str, typing.any] = {}, host: str = None, wait_result: typing.union[int, float] = None, message_ttl: typing.union[int, float] = None) typing.any Sends a message to the queue. A worker will run the task s function when it receives the message. Parameters args Arguments that will be passed to task on execution. kwargs Keyword arguments that will be passed to task on execution. host Send this task to specific host. host will be appended to the queue name. If host is localhost, hostname of the server will be appended to the queue name. wait_result Wait for result from worker for wait_result seconds. If timeout occurs, ResultTimeout is raised. If excecption occurs in worker, RemoteException is raised. message_ttl If set, message will be destroyed in queue after message_ttl seconds. Returns Result from worker if wait_result is set, else None. 3.3 Config Class class kuyruk.config Kuyruk configuration object. Default values are defined as class attributes. Additional attributes may be added by extensions. EAGER = False Run tasks in the process without sending to queue. Useful in tests. RABBIT_HOST = 'localhost' RabbitMQ host. RABBIT_PASSWORD = 'guest' RabbitMQ password. RABBIT_PORT = 5672 RabbitMQ port. RABBIT_USER = 'guest' RabbitMQ user. RABBIT_VIRTUAL_HOST = '/' RabbitMQ virtual host. 18 Chapter 3. API Reference

WORKER_LOGGING_LEVEL = 'INFO' Logging level of root logger. WORKER_MAX_LOAD = None Pause consuming queue when the load goes above this level. WORKER_MAX_RUN_TIME = None Gracefully shutdown worker after running this seconds. from_dict(d: typing.dict[str, typing.any]) None Load values from a dict. from_env_vars() None Load values from environment variables. Keys must start with KUYRUK_. from_object(obj: typing.any) None Load values from an object. from_pyfile(filename: str) None Load values from a Python file. 3.4 Exceptions exception kuyruk.exceptions.discard The task may raise this if it does not want to process the message. The message will be dropped. typ- exception kuyruk.exceptions.heartbeaterror(exc_info: ing.tuple[typing.type[baseexception], BaseException, traceback]) None Raised when there is problem while sending heartbeat during task execution. exception kuyruk.exceptions.kuyrukerror Base class for Kuyruk exceptions. exception kuyruk.exceptions.reject The task may raise this if it does not want to process the message. The message will be requeued and delivered to another worker. exception kuyruk.exceptions.remoteexception(type_: typing.type, value: Exception, traceback: traceback) None Raised from kuyruk.task.send_to_queue() if wait_result is set and exception is raised on the worker while running the task. exception kuyruk.exceptions.resulttimeout Raised from kuyruk.task.send_to_queue() if wait_result is set and reply is not received in wait_result seconds. exception kuyruk.exceptions.timeout Raised if a task exceeds it s allowed run time. 3.4. Exceptions 19

20 Chapter 3. API Reference

CHAPTER 4 Indices and tables genindex search 21

22 Chapter 4. Indices and tables

Python Module Index k kuyruk.exceptions, 19 kuyruk.signals, 7 23

24 Python Module Index

Index A apply() (kuyruk.task method), 18 C channel() (kuyruk.kuyruk method), 17 Config (class in kuyruk), 18 connection() (kuyruk.kuyruk method), 17 D Discard, 19 E EAGER (kuyruk.config attribute), 18 F from_dict() (kuyruk.config method), 19 from_env_vars() (kuyruk.config method), 19 from_object() (kuyruk.config method), 19 from_pyfile() (kuyruk.config method), 19 H HeartbeatError, 19 K Kuyruk (class in kuyruk), 17 kuyruk.exceptions (module), 19 kuyruk.signals (module), 7 KuyrukError, 19 N name (kuyruk.task attribute), 18 R RABBIT_HOST (kuyruk.config attribute), 18 RABBIT_PASSWORD (kuyruk.config attribute), 18 RABBIT_PORT (kuyruk.config attribute), 18 RABBIT_USER (kuyruk.config attribute), 18 RABBIT_VIRTUAL_HOST (kuyruk.config attribute), 18 Reject, 19 RemoteException, 19 ResultTimeout, 19 S send_to_queue() (kuyruk.task method), 18 T Task (class in kuyruk), 17 task() (kuyruk.kuyruk method), 17 task_error (in module kuyruk.signals), 8 task_failure (in module kuyruk.signals), 8 task_init (in module kuyruk.signals), 7 task_postapply (in module kuyruk.signals), 7 task_postrun (in module kuyruk.signals), 8 task_postsend (in module kuyruk.signals), 9 task_preapply (in module kuyruk.signals), 7 task_prerun (in module kuyruk.signals), 8 task_presend (in module kuyruk.signals), 9 task_success (in module kuyruk.signals), 8 Timeout, 19 W worker_failure (in module kuyruk.signals), 9 worker_init (in module kuyruk.signals), 9 WORKER_LOGGING_LEVEL (kuyruk.config attribute), 18 WORKER_MAX_LOAD (kuyruk.config attribute), 19 WORKER_MAX_RUN_TIME (kuyruk.config attribute), 19 worker_shutdown (in module kuyruk.signals), 10 worker_start (in module kuyruk.signals), 9 25