{"id":7212,"library":"faktory","title":"Faktory Python Worker","description":"Faktory is a polyglot background job system. The `faktory` Python library provides a complete client and worker implementation, enabling Python applications to push jobs to, and process jobs from, a Faktory server. It supports features like concurrency, retries, custom metadata, scheduled jobs, and graceful shutdown. Version 1.0.0 was recently released, focusing on improved connection reliability and robustness.","status":"active","version":"1.0.0","language":"en","source_language":"en","source_url":"http://github.com/cdrx/faktory_worker_python","tags":["background jobs","queue","worker","faktory","task queue"],"install":[{"cmd":"pip install faktory","lang":"bash","label":"Install Faktory Python Worker"}],"dependencies":[],"imports":[{"symbol":"Worker","correct":"from faktory import Worker"},{"note":"The primary client interaction is via the `faktory.connection()` context manager, which returns a client object. Direct import of `Client` is not the idiomatic usage for the `faktory` library.","wrong":"from faktory import Client","symbol":"Client connection","correct":"import faktory\nwith faktory.connection() as client:"}],"quickstart":{"code":"import faktory\nimport time\nimport logging\nimport os\n\nlogging.basicConfig(level=logging.INFO)\n\n# --- Worker (Consumer) Example ---\ndef add_numbers(x, y):\n    logging.info(f\"Processing job: {x} + {y} = {x + y}\")\n    return x + y\n\ndef run_worker():\n    logging.info(\"Starting Faktory Worker...\")\n    worker = faktory.Worker(\n        queues=['default'],\n        concurrency=1, # Adjust for more parallelism\n        faktory_url=os.environ.get('FAKTORY_URL', 'tcp://localhost:7419')\n    )\n    worker.register('add_numbers', add_numbers)\n    try:\n        worker.run()\n    except KeyboardInterrupt:\n        logging.info(\"Worker shutting down...\")\n\n# --- Client (Producer) Example ---\ndef push_jobs():\n    faktory_url = os.environ.get('FAKTORY_URL', 'tcp://localhost:7419')\n    logging.info(f\"Connecting to Faktory server at {faktory_url}...\")\n    try:\n        with faktory.connection(faktory_url=faktory_url) as client:\n            for i in range(5):\n                x = i * 10\n                y = i + 5\n                client.queue('add_numbers', args=(x, y))\n                logging.info(f\"Enqueued job: add_numbers({x}, {y})\")\n                time.sleep(0.5)\n        logging.info(\"All jobs enqueued.\")\n    except Exception as e:\n        logging.error(f\"Failed to connect or enqueue jobs: {e}\")\n\nif __name__ == '__main__':\n    # To run:\n    # 1. Start Faktory server (e.g., `faktory` in terminal or Docker)\n    # 2. Run the worker: `python your_script.py worker`\n    # 3. Run the client: `python your_script.py client`\n    import sys\n    if len(sys.argv) > 1 and sys.argv[1] == 'worker':\n        run_worker()\n    elif len(sys.argv) > 1 and sys.argv[1] == 'client':\n        push_jobs()\n    else:\n        print(\"Usage: python your_script.py [worker|client]\")","lang":"python","description":"This quickstart demonstrates both a Faktory client (producer) that enqueues jobs and a Faktory worker (consumer) that processes them. Ensure the Faktory server is running and the `FAKTORY_URL` environment variable is set if your server isn't on `tcp://localhost:7419`. Run the worker in one terminal and the client in another."},"warnings":[{"fix":"Set the `FAKTORY_URL` environment variable or pass `faktory_url` parameter with the format `tcp://:password@host:port`. For example: `FAKTORY_URL=tcp://:your_password@localhost:7419`.","message":"Faktory server requires a password in production environments by default since version 0.7.0. The Python client/worker will fail to connect without proper authentication.","severity":"gotcha","affected_versions":"Faktory server >= 0.7.0, Faktory Python worker all versions."},{"fix":"Configure `concurrency` in the `faktory.Worker` constructor. If using `use_threads=True`, ensure your job functions are thread-safe and handle shared resources appropriately.","message":"The default concurrency mode for workers uses `ProcessPoolExecutor`. Be aware of the overhead of multiprocessing when choosing concurrency levels, and consider the implications for global variables if `use_threads=True` is employed.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Review connection handling logic, especially error catching. Ensure `FAKTORY_URL` is correctly configured and the Faktory server is robust. Test thoroughly after upgrade.","message":"The 1.0.0 release of `faktory` introduces fixes for connection reliability and process pool recovery. While not explicit API breaking changes, code relying on previous, potentially unstable, connection behaviors might experience different outcomes or errors that were previously masked.","severity":"breaking","affected_versions":"Upgrading from 0.x to 1.0.0"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Verify the Faktory server is running (`faktory` command). Check the `FAKTORY_URL` environment variable or the `faktory_url` parameter in `faktory.connection()` or `faktory.Worker` constructor to ensure it points to the correct host, port, and includes authentication if required. For example, `export FAKTORY_URL=tcp://localhost:7419`.","cause":"The Faktory server is not running, or the `FAKTORY_URL` is incorrect or unreachable.","error":"It simply hangs at \"Connecting to Faktory...\""},{"fix":"For the client, use `import faktory` and then `with faktory.connection() as client:`. For the worker, use `from faktory import Worker` and then `worker = Worker(...)`.","cause":"Attempting to instantiate `faktory.Client` or `faktory.Worker` directly without the correct import or constructor, or confusing it with a different library's API.","error":"TypeError: 'module' object is not callable (when trying to import `Client` or `Worker` directly)"},{"fix":"Provide the password in the `FAKTORY_URL` string, e.g., `FAKTORY_URL=tcp://:your_password@localhost:7419`.","cause":"The Faktory server is configured to require a password, but the client/worker is not providing one.","error":"faktory.exceptions.ConnectionError: AUTH required"}]}