{"id":26225930,"url":"https://github.com/nativeinstruments/gocept.amqprun","last_synced_at":"2025-04-19T14:54:19.933Z","repository":{"id":57435168,"uuid":"203554419","full_name":"NativeInstruments/gocept.amqprun","owner":"NativeInstruments","description":"gocept.amqprun helps you writing and running AMQP consumers, and sending AMQP messages. It supports AMQP 0-9-1 and integrates with the Zope Tool Kit (ZTK) so you can use adapters, utilities and all the buzz.","archived":false,"fork":false,"pushed_at":"2023-07-27T21:42:31.000Z","size":545,"stargazers_count":2,"open_issues_count":6,"forks_count":0,"subscribers_count":9,"default_branch":"master","last_synced_at":"2025-04-16T21:23:06.922Z","etag":null,"topics":["amqp","python","ztk"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/NativeInstruments.png","metadata":{"files":{"readme":"README.rst","changelog":"CHANGES.rst","contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null}},"created_at":"2019-08-21T09:45:35.000Z","updated_at":"2021-04-29T07:02:31.000Z","dependencies_parsed_at":"2022-09-01T18:40:33.966Z","dependency_job_id":null,"html_url":"https://github.com/NativeInstruments/gocept.amqprun","commit_stats":null,"previous_names":[],"tags_count":49,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NativeInstruments%2Fgocept.amqprun","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NativeInstruments%2Fgocept.amqprun/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NativeInstruments%2Fgocept.amqprun/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NativeInstruments%2Fgocept.amqprun/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/NativeInstruments","download_url":"https://codeload.github.com/NativeInstruments/gocept.amqprun/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249718658,"owners_count":21315086,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["amqp","python","ztk"],"created_at":"2025-03-12T19:18:18.790Z","updated_at":"2025-04-19T14:54:19.909Z","avatar_url":"https://github.com/NativeInstruments.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"==============\ngocept.amqprun\n==============\n\n.. image:: https://img.shields.io/codecov/c/github/NativeInstruments/gocept.amqprun   :alt: Codecov\n\n\n``gocept.amqprun`` helps you writing and running AMQP consumers, and sending\nAMQP messages. It currently only supports AMQP 0-9-1 and integrates with the\nZope Tool Kit (ZTK) so you can use adapters, utilities and all the buzz.\n\n.. contents:: :depth: 1\n\n\nBasic concepts and terms\n========================\n\n* A *message handler* is a function which is bound with a routing key to\n  exactly one queue. It is called for each message on that queue, and may\n  return a list of messages as a result.\n\n* The result messages of one handled message are sent in one transaction\n  together with the ACK of the handled message.\n\n* When an exception is raised during message processing, the transaction is\n  aborted. (The received message would be NACKed if RabbitMQ was supporting\n  it.)\n\n* A message handler handles exactly one message at a time. Multiple messages\n  can be processed at the same time using multiple processes. (Each process is\n  single-threaded.)\n\n\nThings you don't need to take care of\n=====================================\n\n* Socket handling and locking for communicating with the AMQP broker\n\n* Transaction handling\n\n* Message ids\n\n  * Each outgoing message gets an email-like message id.\n\n  * The correlation id of each outgoing message is set to the message id of\n    the incoming message.\n\n  * Each outgoing message gets a custom references header which is set to the\n    incoming message's reference header plus the incoming message's message\n    id.\n\n\nGetting started: receiving messages\n===================================\n\nTo get started, define a function which does the work. In this example, we log\nthe message body and send a message. The ``declare`` decorator takes two\narguments, the queue name and the routing key (you can also pass in a list to\nbind the function to multiple routing keys). The ``declare`` decorator also\nsupports an optional ``arguments`` argument that is a dictionary to be passed\nto the AMQP queue_declare call to, e.g., support mirrored queues on RabbitMQ.\nThe optional argument ``principal`` specifies to wrap the handler call into a\nzope.security interaction using the given principal id (you need the\n``[security]`` setup.py extra to use this integration functionality).\n\n::\n\n    import logging\n    import gocept.amqprun.handler\n    import gocept.amqprun.message\n\n    log = logging.getLogger(__name__)\n\n    @gocept.amqprun.handler.declare('test.queue', 'test.routing')\n    def log_message_body(message):\n        log.info(message.body)\n        msg = gocept.amqprun.message.Message(\n            header=dict(content_type='text/plain'),\n            body=u'Thank you for your message.',\n            routing_key='test.thank.messages')\n        return [msg]\n\n\nThe handler function needs to be registered as a named utility. With ZCML this\nlooks like this [#grok]_::\n\n    \u003cconfigure xmlns=\"http://namespaces.zope.org/zope\"\u003e\n      \u003cutility component=\"your.package.log_message_body\" name=\"basic\" /\u003e\n    \u003c/configure\u003e\n\nTo set up a server, it's recommended to create a buildout. The following\nbuildout creates a config file for ``gocept.amqprun`` as well as a ZCML file\nfor the component configuration and uses ZDaemon to daemonize the process::\n\n    [buildout]\n    parts =\n            config\n            zcml\n            app\n            server\n\n    [deployment]\n    name = queue\n    recipe = gocept.recipe.deploymentsandbox\n    root = ${buildout:directory}\n\n    [config]\n    recipe = lovely.recipe:mkfile\n    path = ${deployment:etc-directory}/queue.conf\n\n    amqp-hostname = localhost\n    amqp-username = guest\n    amqp-password = guest\n    amqp-virtualhost = /\n\n    eventlog =\n        \u003ceventlog\u003e\n          level DEBUG\n          \u003clogfile\u003e\n            formatter zope.exceptions.log.Formatter\n            path STDOUT\n          \u003c/logfile\u003e\n        \u003c/eventlog\u003e\n    amqp-server =\n        \u003camqp-server\u003e\n          hostname ${:amqp-hostname}\n          username ${:amqp-username}\n          password ${:amqp-password}\n          virtual_host ${:amqp-virtualhost}\n        \u003c/amqp-server\u003e\n\n    content =\n        ${:eventlog}\n        ${:amqp-server}\n        \u003cworker\u003e\n          component-configuration ${zcml:path}\n        \u003c/worker\u003e\n        \u003csettings\u003e\n          your.custom.settings here\n        \u003c/settings\u003e\n\n    [zcml]\n    recipe = lovely.recipe:mkfile\n    path = ${deployment:etc-directory}/queue.zcml\n    content =\n        \u003cconfigure xmlns=\"http://namespaces.zope.org/zope\"\u003e\n          \u003cinclude package=\"your.package\" /\u003e\n        \u003c/configure\u003e\n\n    [app]\n    recipe = zc.recipe.egg:script\n    eggs =\n       gocept.amqprun\n       your.package\n       zope.exceptions\n    arguments = '${config:path}'\n    scripts = server=app\n\n    [server]\n    recipe = zc.zdaemonrecipe\n    deployment = deployment\n    program = ${buildout:bin-directory}/app\n\n\n.. [#grok] It's likely that there will be a special ZCML statement and/or grok\n   support to make registering of handlers easier.\n\n\nSending messages\n================\n\nIf all you want to do is send messages, you don't have to register any\nhandlers, but can use ``gocept.amqprun.server.Server.send()`` directly. While\nthe handlers usually run in their own process, started by the ``server``\nentrypoint (as described above), if you're just sending messages, you can also\nskip the extra process and run the ``gocept.amqprun.server.Server`` in your\noriginal process. Here is some example code to do that::\n\n    def start_server(**kw):\n        server = gocept.amqprun.server.Server(kw, setup_handlers=False)\n        server.connect()\n        return server\n\n(When you're using the ZCA, you'll probably want to register the ``Server`` as\na utility at that point, too, so clients can access it to send messages\neasily.)\n\n\nSettings\n========\n\nFor application-specific settings gocept.amqprun makes the ``\u003csettings\u003e``\nsection from the configuration available via an ``ISettings`` utility::\n\n    settings = zope.component.getUtility(\n        gocept.amqprun.interfaces.ISettings)\n    settings.get('your.settings.key')\n\n\nLimitations\n===========\n\n* Currently all messages are sent and received through the `amq.topic`\n  exchange. Other exchanges are not supported at the moment.\n\n\nInterfacing with the file system\n================================\n\nReading\n-------\n\nThere is a ``send_files`` entrypoint in the setup.py. It can be configured with\nthree arguments: The path of the zconfig file, a watch path and a routing key.\nIt reads new files in the directory named ``new`` in the watch path and sends\na message with its content as the body and the filename as an X-Filename header\nto the route. Sent files are moved to the directory called ``cur`` in the\nwatch path.\n\nDevelopment\n===========\n\nYou can set the AMQP server parameters for running the tests via environment\nvariables:\n\n:AMQP_HOSTNAME:\n    default: localhost\n\n:AMQP_USERNAME:\n    default: guest\n\n:AMQP_PASSWORD:\n    default: guest\n\n:AMQP_VIRTUALHOST:\n    default: None, so a vhost with a temporary name is created and\n    deleted automatically (using ``AMQP_RABBITMQCTL`` command)\n\n:AMQP_RABBITMQCTL:\n   default: 'sudo rabbitmqctl'\n\nThe source code is available in the mercurial repository at\nhttps://github.com/gocept/gocept.amqprun\n\nPlease report any bugs you find at\nhttps://github.com/gocept/gocept.amqprun/issues\n\n\nbin/test_sender and bin/test_server\n-----------------------------------\n\n``test_sender`` and ``test_server`` are scripts that provide basic sender and\nhandler capabilities to smoke test the behaviour of our current implementation.\nWhen started ``test_sender`` emits 10 messages routed to ``test.routing``.\n``test.server`` declares a ``test.queue`` which all messages from\n``test.routing`` are sent to and a handler logging every incoming message from\n``test.queue``.\n\nbin/test_send_files\n-------------------\n``test_send_files`` starts a server that watches the ./testdir/new directory\nand sends files copied into it as an amqp message to ``test.routing``. Its\nentrypoint is ``gocept.amqprun.readfiles:main``.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnativeinstruments%2Fgocept.amqprun","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnativeinstruments%2Fgocept.amqprun","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnativeinstruments%2Fgocept.amqprun/lists"}