DefStream-RabbitMQ 0.1.1.2__py3-none-any.whl → 0.1.1.3__py3-none-any.whl

defstream_rabbitmq-0.1.1.3.dist-info/METADATA

@@ -0,0 +1,239 @@
+Metadata-Version: 2.4
+Name: DefStream-RabbitMQ
+Version: 0.1.1.3
+Summary: RabbitMQ broker adapter for DefStream
+Home-page: https://github.com/yong5eon/DefStream-RabbitMQ
+Author: Heo Yongseon
+Project-URL: Source, https://github.com/yong5eon/DefStream-RabbitMQ
+Project-URL: Issues, https://github.com/yong5eon/DefStream-RabbitMQ/issues
+Project-URL: Releases, https://github.com/yong5eon/DefStream-RabbitMQ/releases
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: DefStream>=0.1.0
+Requires-Dist: pika>=1.3.2
+Dynamic: author
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: license-file
+Dynamic: project-url
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+# DefStream-RabbitMQ
+
+**한국어** | [English](./README.en.md)
+
+DefStream에서 RabbitMQ를 사용할 수 있게 해주는 브로커 어댑터입니다.
+일반 큐, Exchange 라우팅, 스트림 이력 읽기, 동기 RPC를 제공하며,
+DefStream Worker에 연결해 작업을 스레드·프로세스 풀에서 실행할 수 있습니다.
+내부 클라이언트로 Pika를 사용합니다.
+
+## 설치
+
+Python **3.9 이상**과 접속 가능한 RabbitMQ 서버가 필요합니다.
+
+```shell
+python -m pip install DefStream-RabbitMQ
+```
+
+`DefStream>=0.1.0`과 `pika>=1.3.2`도 함께 설치됩니다.
+배포 패키지 이름은 `DefStream-RabbitMQ`이고 import 경로는
+`DefStream.Broker.Implements.RabbitMQ`입니다.
+
+## 큐에 보내고 받기
+
+로컬 RabbitMQ의 `guest` 계정을 사용하는 예제입니다.
+운영에서는 별도 계정과 환경변수·비밀 저장소를 사용하세요.
+예제는 `defstream.example.rabbitmq` 큐를 만들며 실행 후에도 큐를 유지합니다.
+
+```python
+from DefStream.Broker.Implements.RabbitMQ import Configuration, Connection
+
+
+connection = Connection(Configuration(
+  host='127.0.0.1',
+  port=5672,
+  username='guest',
+  password='guest',
+))
+try:
+  connection.connect()
+  connection.create_queue('defstream.example.rabbitmq')
+  queue = connection.queue('defstream.example.rabbitmq')
+  queue.send({'message': 'Hello, DefStream!'})
+  event = queue.pop(timeout=1000)
+  if event is not None:
+    print(event.body)
+    event.ack()
+finally:
+  connection.close()
+```
+
+메시지는 기본 JSON 코덱으로 직렬화됩니다.
+`pop()` 제한 시간은 **밀리초**이며, 양수 제한 시간에 메시지가 없으면 `None`을 반환합니다.
+`None` 또는 `0`은 무기한 대기입니다.
+처리가 성공하면 `ack()`, 재전달하려면 `nack()`, 거부하려면 `reject()`를 호출하세요.
+거부한 메시지는 브로커의 dead-letter 설정이 있으면 해당 목적지로, 없으면 폐기됩니다.
+
+## 연결 설정
+
+| 옵션 | 의미 |
+| --- | --- |
+| `host`, `port` | RabbitMQ 주소와 AMQP 포트 |
+| `username`, `password` | 인증 정보 |
+| `vhost` | 가상 호스트, 기본값 `/` |
+| `ssl` | TLS 사용 여부, 기본값 `False` |
+| `timeout` | blocked-connection 제한 시간, 밀리초 |
+| `heartbeat` | 현재 구현은 `int(heartbeat * 2 / 1000)`초로 변환하여 Pika에 전달 |
+| `encode`, `decode` | 메시지 코덱, 기본값 JSON |
+
+`timeout`은 모든 작업에 대한 전체 실행 제한 시간이 아닙니다.
+일반 연결의 heartbeat는 애플리케이션 작업·유휴 시간에 맞게 설정하고 처리되도록 관리하세요.
+연결과 그 리소스는 **소유 스레드에서만 사용**해야 하며, 스레드·프로세스 사이에 공유하지 마세요.
+
+## Worker로 작업 처리하기
+
+다음은 큐와 오류 큐를 준비한 후 작업을 소비하는 실행 파일입니다.
+
+```python
+from signal import SIGINT, signal
+
+from DefStream.Broker.Implements.RabbitMQ import (
+  Configuration,
+  Connection,
+  Reject,
+  Subscription,
+)
+from DefStream.Worker import Run, ThreadPool, Worker, WorkerSetup, declare
+
+
+class Add(
+  Run,
+  parameters=Subscription(
+    queue='defstream.example.rabbitmq.add',
+    qos=4,
+    error='defstream.example.rabbitmq.add.error',
+  ),
+  on_error=Reject(),
+):
+  def run(
+    self,
+    a: int,
+    b: int,
+  ):
+    return a + b
+
+
+class Prepare(WorkerSetup):
+  def __call__(
+    self,
+    worker: Worker,
+  ) -> None:
+    for task in worker.tasks:
+      declare(
+        task=task,
+        broker=worker.broker,
+      )
+
+
+if __name__ == '__main__':
+  worker = Worker(
+    Connection(Configuration(
+      host='127.0.0.1',
+      port=5672,
+      username='guest',
+      password='guest',
+    )),
+    ThreadPool(4),
+    setups=Prepare(),
+  )
+  worker.add(Add)
+  signal(
+    SIGINT,
+    lambda *_: worker.stop(),
+  )
+  worker.run()
+```
+
+다른 프로세스에서 같은 큐에 `{'a': 10, 'b': 20}`을 보내면 처리됩니다.
+Worker는 실행과 완료 훅이 끝난 뒤 ACK하고, 실패하면 지정한 정책을 적용합니다.
+`on_error`를 생략하면 기본값은 `Requeue()`입니다.
+
+`Subscription` 옵션:
+
+- `queue`: 작업 큐 이름.
+- `qos`: 이 구독의 미확인 메시지 수 제한. 기본 소비자 값은 1이며, 0은 무제한입니다.
+  Worker의 공유 풀 크기와 별개입니다.
+- `error`: `declare()`가 생성하고 연결할 오류 큐 이름. 거부된 메시지의 DLQ입니다.
+- `offset`: RabbitMQ 스트림 구독에 사용할 정수 오프셋.
+
+`Subscription` 객체 생성이나 `consumer.subs()`는 큐를 선언하지 않습니다.
+작업용 `declare()`는 일반 durable 큐와 선택적 DLQ를 준비하며,
+스트림 큐나 Exchange 바인딩을 자동 생성하지 않습니다.
+기존 큐의 선언 옵션이 다르면 실패하며 자동 삭제·재생성하지 않습니다.
+
+## 동기 RPC
+
+실행 중인 Worker가 있는 큐에 `call()`을 사용하면 `Run.run()`의 반환값을 받습니다.
+아래 코드는 앞의 직접 연결 예제에서 `connect()`와 `close()` 사이에 사용하세요.
+
+```python
+result = connection.queue('defstream.example.rabbitmq.add').call(
+  {'a': 10, 'b': 20},
+  timeout=5,
+)
+print(result)
+```
+
+- `timeout`은 **초** 단위이며 응답이 없으면 `TimeoutError`가 발생합니다.
+  이미 전달된 서버 작업을 취소하거나 전체 연결·정리 시간을 엄격히 제한하는 값은 아닙니다.
+- 각 호출은 전용 연결과 임시 응답 큐를 사용하고 종료 시 정리합니다.
+- 서버가 요청을 거부하면 `DefStream.Broker.RemoteError`가 발생합니다.
+  재큐잉은 최종 오류 응답 없이 재시도할 수 있습니다.
+- 응답 발행과 요청 ACK는 원자적이지 않습니다. RPC에서도 중복 실행에 대비하세요.
+
+공유 `Run` 클래스를 사용하는 애플리케이션은 코어의
+`request(body, task=Add, broker=connection, timeout=5)`도 사용할 수 있습니다.
+
+## Exchange와 스트림
+
+- `connection.exchange(name)`은 `send()`와 `call()`을 제공합니다.
+  `event=`가 라우팅 키입니다. Exchange와 큐·바인딩을 먼저 선언하세요.
+- Exchange RPC가 여러 큐로 라우팅되면 여러 곳에서 실행될 수 있으며,
+  클라이언트는 첫 일치 응답만 받습니다. 일반 RPC에는 단일 목적지를 사용하세요.
+- `create_exchange()`, `bind_exchange_to_queue()`, `bind_exchange_to_exchange()`로 라우팅을 구성합니다.
+  각각에 대응하는 `delete_...` 또는 `unbind_...` 메서드도 있습니다.
+- `create_stream()`으로 스트림 큐를 만든 뒤 `connection.stream(name)`의
+  `send()`와 `read(offset=0, timeout=1000)`을 사용합니다. 읽기 제한 시간은 밀리초입니다.
+  읽은 이벤트는 이터레이터가 다음 단계로 진행될 때 자동 ACK합니다.
+- `delete_queue()`, `delete_stream()`, `delete_exchange()`는 리소스를 삭제하므로
+  애플리케이션 소유 리소스에만 사용하세요.
+
+## 운영 시 주의사항
+
+- 최소 한 번(at-least-once) 전달을 전제로 멱등 작업을 작성하세요.
+- 무제한 재큐잉은 영구 오류 메시지의 반복 실행을 만들 수 있습니다. DLQ와 재시도 정책을 설계하세요.
+- 소비자 연결에서 긴 작업을 직접 실행하지 말고 Worker의 풀을 사용하세요.
+- 작업 훅에서 발행하려면 훅이 실행되는 스레드·프로세스 안에 별도 생산자 연결을 만드세요.
+- `worker.stop()`은 처리 중인 작업과 ACK를 기다린 뒤 연결과 풀을 닫습니다.
+  강제 종료 또는 종료 대기 시간 제한은 제공하지 않습니다.
+
+## 더 알아보기
+
+- [DefStream 사용 설명서](https://github.com/yong5eon/DefStream#readme): 작업, 풀, 훅, 검증, Inspector, 대시보드·콘솔
+- [큐·Exchange 예제](./sample/Sample.py)
+- [독립 실행 RPC 예제](./sample/Sample.RPC.py)
+- [스트림 예제](./sample/Sample.Stream.py)
+- [릴리즈와 변경 내역](https://github.com/yong5eon/DefStream-RabbitMQ/releases)
+
+GNU GPL v3 라이선스를 사용합니다. 자세한 조건은 [LICENSE](./LICENSE)를 확인하세요.

{defstream_rabbitmq-0.1.1.2.dist-info → defstream_rabbitmq-0.1.1.3.dist-info}/RECORD

@@ -9,8 +9,8 @@ DefStream/Broker/Implements/RabbitMQ/Serializer.py,sha256=ylwIBJ0blftq2W9usuYvjS
 DefStream/Broker/Implements/RabbitMQ/Stream.py,sha256=9E7R_bX_kDZ3VIH7hkMpP-Z7zGbJTonU8V6q_KT3YRI,2283
 DefStream/Broker/Implements/RabbitMQ/Subscription.py,sha256=0ACs8skbn_s9UfricBDf59hT0F6G3ljO4aUrkpLuI9g,1284
 DefStream/Broker/Implements/RabbitMQ/__init__.py,sha256=Ndt5yNXcgecN1mj0Qv7M32LUFK96WKmSi88wKMB1ZdU,673
-defstream_rabbitmq-0.1.1.2.dist-info/licenses/LICENSE,sha256=OXLcl0T2SZ8Pmy2_dmlvKuetivmyPd5m1q-Gyd-zaYY,35149
-defstream_rabbitmq-0.1.1.2.dist-info/METADATA,sha256=VCEpTp6CDluZN9ptt2hi4a1nmROppwPCM0J_M8_cQRo,8701
-defstream_rabbitmq-0.1.1.2.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
-defstream_rabbitmq-0.1.1.2.dist-info/top_level.txt,sha256=zsnisIu5wHL4b7VM8e9AggG9KTSdUU4morFqpb8YWFs,10
-defstream_rabbitmq-0.1.1.2.dist-info/RECORD,,
+defstream_rabbitmq-0.1.1.3.dist-info/licenses/LICENSE,sha256=OXLcl0T2SZ8Pmy2_dmlvKuetivmyPd5m1q-Gyd-zaYY,35149
+defstream_rabbitmq-0.1.1.3.dist-info/METADATA,sha256=SRhV3AAy1XwU3uwaI-tFnFMZjqOP1zEmghZorysWznc,9242
+defstream_rabbitmq-0.1.1.3.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+defstream_rabbitmq-0.1.1.3.dist-info/top_level.txt,sha256=zsnisIu5wHL4b7VM8e9AggG9KTSdUU4morFqpb8YWFs,10
+defstream_rabbitmq-0.1.1.3.dist-info/RECORD,,

defstream_rabbitmq-0.1.1.2.dist-info/METADATA

@@ -1,191 +0,0 @@
-Metadata-Version: 2.4
-Name: DefStream-RabbitMQ
-Version: 0.1.1.2
-Summary: RabbitMQ broker adapter for DefStream
-Home-page: https://github.com/yong5eon/DefStream-RabbitMQ
-Author: Heo Yongseon
-Project-URL: Source, https://github.com/yong5eon/DefStream-RabbitMQ
-Project-URL: Issues, https://github.com/yong5eon/DefStream-RabbitMQ/issues
-Project-URL: Releases, https://github.com/yong5eon/DefStream-RabbitMQ/releases
-Classifier: Programming Language :: Python :: 3.9
-Classifier: Programming Language :: Python :: 3.10
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Programming Language :: Python :: 3.13
-Classifier: Programming Language :: Python :: 3.14
-Requires-Python: >=3.9
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: DefStream>=0.1.0
-Requires-Dist: pika>=1.3.2
-Dynamic: author
-Dynamic: classifier
-Dynamic: description
-Dynamic: description-content-type
-Dynamic: home-page
-Dynamic: license-file
-Dynamic: project-url
-Dynamic: requires-dist
-Dynamic: requires-python
-Dynamic: summary
-
-# DefStream-RabbitMQ
-
-## CI and PyPI releases
-
-The `CI` workflow tests PRs targeting `master` and pushes to `master` on Python
-3.9 through 3.14. It builds all three DefStream packages from source, installs
-their wheels in a clean environment, and runs this repository's tests with
-RabbitMQ 4.1 and Redis 7.4 service containers. The current repository uses the
-event commit; sibling repositories use their `master` branches, with resolved
-commit IDs recorded in the log. All three GitHub repositories must be accessible.
-This bootstrap setup does not require existing PyPI releases and does not
-certify compatibility with previously published dependencies.
-
-There is no `VERSION` or `pyproject.toml` file. `setup.py` configures
-`setuptools-scm` via `setup_requires`; `python -m build` resolves the build
-dependency in isolation. This legacy declaration may emit a deprecation warning.
-`setuptools-scm` derives versions from Git tags.
-CI fetches full history and creates a local candidate tag
-`<RELEASE_SERIES>.<PATCH>.<github.run_number>` (for example, `0.1.3.123`) on
-every `master` push. Source changes increment PATCH by one; all other changes
-keep MAJOR.MINOR.PATCH. BUILD is always the Actions run number:
-`0.1.3.123` -> `0.1.3.124` (docs) -> `0.1.4.125` (source).
-The highest matching version in pre-push history supplies the base, keeping
-reruns stable. The four-part value is the full public PyPI version.
-New tags have no `v` prefix; existing `v` tags remain readable.
-PRs only run tests using their Git-derived development version without a tag.
-The complete push range is compared, including additions, deletions, and
-renames. Changes only to tests, docs, samples, workflows, or `setup.py` increase
-only BUILD. PyPI files cannot be overwritten; every upload has a distinct
-version identifier. Change
-`RELEASE_SERIES` in the workflow to start a new major/minor series. No version
-commit or version-update PR is created; run numbers can have gaps.
-
-After all tests pass, the publish job pushes the release tag to the tested
-commit before uploading the verified artifacts. A tag may exist if uploading
-subsequently fails; retry the run and check PyPI for publication status.
-Existing tags on other commits are never overwritten. Allow the workflow's
-`GITHUB_TOKEN` to write contents and permit numeric four-part tags
-in any tag rulesets.
-
-After PyPI upload succeeds (or a rerun confirms the version is fully
-published), CI creates a GitHub Release titled and tagged with the same
-version, with automatically generated notes and the verified wheel and sdist
-attached. New releases remain drafts until both assets are uploaded. A retry
-reuses the release, replaces matching assets with the verified files, and
-publishes it. PyPI upload failures prevent this step. The existing write-enabled
-`GITHUB_TOKEN` is sufficient; no extra token secret is required. PyPI's project
-links include the GitHub Releases page for change history.
-
-Fetch tags with `git fetch --tags` for local builds. Tagged commits produce
-release versions; later commits produce development versions, with local
-suffixes for dirty trees. Build from a Git checkout or a published sdist, not
-a GitHub source ZIP without Git metadata. Installed versions are available via
-`importlib.metadata.version('DefStream-RabbitMQ')`. Before migration, tag the
-exact source commits of existing PyPI releases in all three repositories,
-using their version numbers as tags.
-Untagged SCM dependencies may resolve below their required minimum version;
-initial release tags also provide the starting PATCH for numeric builds.
-A tag such as `0.1.3` must name the commit used to publish that version, not
-an arbitrary current commit. Adding that tag does not edit sources or upload
-anything to PyPI.
-A new release series needs a source change or an existing matching release tag
-before it can produce builds. Its first source release starts at PATCH 0.
-Build counter regressions fail explicitly. Legacy `.postN` tags remain
-readable; numeric builds sort above post releases of a three-part base.
-
-Only after all six Python checks pass does a separate publish job upload the
-exact Python 3.13 build artifacts. A fully published version is skipped on a
-rerun; first-attempt collisions, incomplete releases, and unexpected network
-errors fail. Active runs are not cancelled; older pending runs may be superseded.
-
-Configure `PYPI_API_TOKEN` as a repository Actions secret or a secret in the
-`pypi` environment. Restrict that environment to `master`; omit approval rules
-for fully automatic releases. Protect `master` with required PRs and all six
-`Test Python 3.x` checks, not the push-only `Publish PyPI` job. Never commit the
-token. Publish the core before this adapter so users can resolve its dependency.
-
-RabbitMQ broker adapter for DefStream, distributed separately from the core.
-Requires Python 3.9 or newer.
-
-## Installation
-
-```shell
-pip install DefStream-RabbitMQ
-```
-
-This installs `DefStream>=0.1.0` and `pika>=1.3.2`. The distribution name is
-`DefStream-RabbitMQ`; the Python import path remains
-`DefStream.Broker.Implements.RabbitMQ`.
-
-## Usage
-
-```python
-from DefStream.Broker.Implements.RabbitMQ import (
-	Configuration,
-	Connection,
-)
-
-broker = Connection(Configuration(
-	host='127.0.0.1',
-	port=5672,
-	username='guest',
-	password='guest',
-))
-broker.connect()
-try:
-	broker.create_queue('tasks')
-	broker.queue('tasks').send({'message': 'hello'})
-finally:
-	broker.close()
-```
-
-A reachable RabbitMQ server is required. Use connections and their resources
-on the thread that owns them.
-
-The adapter provides queues, exchanges, streams, subscriptions, error policies,
-and synchronous queue/exchange RPC. Use its `Connection` with
-`DefStream.Worker.Worker` for worker execution.
-
-## Source layout
-
-The contents of the former `DefStream/src/Broker/Implements/RabbitMQ` directory
-now live directly in this project's [src](./src) directory. Packaging maps that
-directory to `DefStream.Broker.Implements.RabbitMQ`; this distribution does not
-own or overwrite the parent packages supplied by DefStream.
-
-## Development
-
-With the core and both adapters checked out as sibling directories, run this
-from their common parent using your virtual environment's Python:
-
-```powershell
-python -m pip install --config-settings editable_mode=strict -e .\DefStream
-python -m pip install -e .\DefStream-RabbitMQ -e .\DefStream-Redis
-python -m unittest discover -s .\DefStream-RabbitMQ\test -p "test_*.py"
-```
-
-The core uses strict editable mode to prevent the adapters' editable namespace
-entries from masking its packages. Keep the core's generated `build` link tree;
-reinstall the core after adding or removing its modules. Adapters use default
-editable mode.
-
-RabbitMQ-specific tests live in this project's `test` directory, covering
-resource methods, subscriptions, consumers, RPC, and broker integration.
-Broker examples live in `sample`. Shared Worker, Inspector, and cross-adapter
-contract tests remain in the DefStream repository and require both adapters.
-
-Run `python -m unittest discover -s test -p "test_*.py"` from this project
-directory after installation. Integration tests are opt-in via
-`DEFSTREAM_RABBITMQ_TESTS=1`; ordinary unit tests do not require a running broker
-or the Redis adapter.
-
-Do not combine editable installs with a `site-packages/DefStream` link pointing
-directly at the core source: installing adapter files through that link can
-write into the core checkout. Remove such a link before installing the projects.
-Reinstall after changing package metadata or dependencies.
-
-## License
-
-See [LICENSE](./LICENSE), copied unchanged from DefStream.