Metadata-Version: 2.4
Name: multicast
Version: 2.0.9a3
Summary: Multicast Python Module to provide for Send/Recv functionality.
Maintainer-email: reactive-firewall <reactive-firewall@users.noreply.github.com>
Project-URL: Bug Tracker, https://github.com/reactive-firewall/multicast/issues
Project-URL: License, https://raw.githubusercontent.com/reactive-firewall/multicast/HEAD/LICENSE.md
Project-URL: Documentation, https://reactive-firewallmulticast.readthedocs.io/en/stable
Project-URL: Repository, https://github.com/reactive-firewall/multicast.git
Keywords: multicast,RFC-1112,udp-protocol,network-programming,POSIX-compliant,socket,many-to-many,client-server
Classifier: Intended Audience :: Developers
Classifier: Operating System :: POSIX
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Networking
Requires-Python: !=3.13.0,!=3.9.10,!=3.9.11,!=3.9.12,!=3.9.13,!=3.9.14,!=3.9.15,!=3.9.16,!=3.9.17,!=3.9.18,!=3.9.19,!=3.9.7,!=3.9.8,<3.14.0,>=3.9.6
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
License-File: LICENSE.md
Dynamic: license-file

# Multicast Python Module

![Mcast Logo](https://github.com/reactive-firewall/multicast/blob/stable/Logo.svg)

## Introduction

The `multicast` package is a Python library that simplifies sending and receiving multicast network
messages. It provides classes and tools for implementing multicast communication in Python
applications, making it straightforward to work with multicast sockets.

## Features

- **Easy Multicast Communication**: Send and receive messages over multicast networks with
  simple `Python` interfaces.
- **Command-Line Tools**: Includes command-line utilities for quick multicast prototyping.
- **Cross-Python Compatibility**: Designed to work with multiple Python versions.
- **Support for UDP**: Works with UDP via IPv4 multicast addresses.

## Status

### Master (Development)

[![CircleCI](https://circleci.com/gh/reactive-firewall/multicast/tree/master.svg?style=svg)](https://circleci.com/gh/reactive-firewall/multicast/tree/master)
[![CI](https://github.com/reactive-firewall/multicast/actions/workflows/Tests.yml/badge.svg?branch=master)](https://github.com/reactive-firewall/multicast/actions/workflows/Tests.yml)
[![Minimal Acceptance Tests](https://github.com/reactive-firewall/multicast/actions/workflows/CI-MATs.yml/badge.svg?branch=master)](https://github.com/reactive-firewall/multicast/actions/workflows/CI-MATs.yml)
[![Appveyor](https://ci.appveyor.com/api/projects/status/0h5vuexyty9lbl81/branch/master?svg=true)](https://ci.appveyor.com/project/reactive-firewall/multicast/branch/master)
[![Documentation Status](https://readthedocs.org/projects/reactive-firewallmulticast/badge/?version=master)](https://reactive-firewallmulticast.readthedocs.io/en/latest/?badge=master)
[![Test Coverage](https://api.codeclimate.com/v1/badges/8a9422860b6a5b6477b5/test_coverage)](https://codeclimate.com/github/reactive-firewall/multicast/test_coverage)
[![Code Coverage](https://codecov.io/gh/reactive-firewall/multicast/branch/master/graph/badge.svg)](https://codecov.io/gh/reactive-firewall/multicast/branch/master/)
[![Bandit](https://github.com/reactive-firewall/multicast/actions/workflows/bandit.yml/badge.svg?branch=master)](https://github.com/reactive-firewall/multicast/actions/workflows/bandit.yml)
[![Code Climate](https://api.codeclimate.com/v1/badges/8a9422860b6a5b6477b5/maintainability)](https://codeclimate.com/github/reactive-firewall/multicast)
[![CodeFactor](https://www.codefactor.io/repository/github/reactive-firewall/multicast/badge)](https://www.codefactor.io/repository/github/reactive-firewall/multicast)
[![codebeat badge](https://codebeat.co/badges/721f752f-289d-457e-af90-487a85f16bf1)](https://codebeat.co/projects/github-com-reactive-firewall-multicast-master)
![Size](https://img.shields.io/github/languages/code-size/reactive-firewall/multicast.svg)
[![Scc Count Badge](https://sloc.xyz/github/reactive-firewall/multicast/?category=code)](https://github.com/reactive-firewall/multicast/)
[![Scc Count Badge](https://sloc.xyz/github/reactive-firewall/multicast/?category=blanks)](https://github.com/reactive-firewall/multicast/)
[![Scc Count Badge](https://sloc.xyz/github/reactive-firewall/multicast/?category=lines)](https://github.com/reactive-firewall/multicast/)
[![Scc Count Badge](https://sloc.xyz/github/reactive-firewall/multicast/?category=comments)](https://github.com/reactive-firewall/multicast/)
![Commits-since](https://img.shields.io/github/commits-since/reactive-firewall/multicast/stable.svg?maxAge=9000)

### Stable (Mainstream)

[![Stable CI](https://github.com/reactive-firewall/multicast/actions/workflows/Tests.yml/badge.svg?branch=stable)](https://github.com/reactive-firewall/multicast/actions/workflows/Tests.yml)
[![Stable Appveyor](https://ci.appveyor.com/api/projects/status/0h5vuexyty9lbl81/branch/stable?svg=true)](https://ci.appveyor.com/project/reactive-firewall/multicast/branch/stable)
[![Stable Code Coverage](https://codecov.io/gh/reactive-firewall/multicast/branch/stable/graph/badge.svg)](https://codecov.io/gh/reactive-firewall/multicast/branch/stable/)
[![CodeQL](https://github.com/reactive-firewall/multicast/actions/workflows/codeql-analysis.yml/badge.svg?branch=stable)](https://github.com/reactive-firewall/multicast/actions/workflows/codeql-analysis.yml)

## Installation

Install the package using `pip`:

```bash
pip install multicast
```

<details><summary>Alternative Methods</summary>

There are many ways to install the module besides using `pip`, but unless you have a specific need,
using `pip` is recommended for most users.

### PEP-668 and externally-managed-environment installs

Users using Homebrew may require additional flags to use `pip`:

```bash
python3 -m pip install --use-pep517 --break-system-packages --user 'multicast>=2.0.8'
```

### Install from Source

*Source builds require development tools including (but not limited to): `git`, and `make`*

```bash
# clone the multicast source repository
git clone "https://github.com/reactive-firewall/multicast.git" multicast
cd multicast
# switch to the stable branch
git checkout stable
# build the multicast module
make -f Makefile build
# install the build
make user-install
# Optionally check the install
python3 -m multicast --version
```

### Developer builds

> [!WARNING]
> **Development Builds** *(e.g. Cutting-Edge)* are not intended as full-fleged releases, however
> updates to the Development Builds are more frequent than releases.

### Legacy egg style install

> [!WARNING]
> **Egg Style Builds** *(Deprecated)* are not supported after version `2.1` :shrug:

```bash
pip install -e "git+https://github.com/reactive-firewall/multicast.git#egg=multicast"
```

</details>

## Getting Started

Below are basic examples to help you start using the `multicast` package.

### Sending Multicast Messages

```python3
from multicast import send

# Create a multicast sender
sender = send.McastSAY()

# Send a message
sender(group='224.0.0.1', port=59259, ttl=1, data='Hello, Multicast!')
```

### Receiving Multicast Messages

```python3
from multicast import recv

# Create a multicast receiver
receiver = recv.McastRECV()

# Receive a message
message = receiver(group='224.0.0.1', port=59259, ttl=1)
print('Received:', message)
```

### Listening for Multicast Messages

```python3
from multicast import hear

# Create a multicast listener
listener = hear.McastHEAR()

# Listen for messages indefinitely
listener(group='224.0.0.1', port=59259, ttl=1)
```

## Command-Line Usage

The `multicast` package provides command-line tools for multicast communication prototyping.

- Read the [Usage](docs/USAGE.md) for details.

## FAQ

- Read the [FAQ](docs/FAQ.md) for common answers.

## Default Settings

- **Multicast Group Address**: `224.0.0.1` (link-local multicast as per
  [RFC 5771](https://tools.ietf.org/html/rfc5771))
- **Default Port**: `59259` (within the dynamic/private port range defined by
  [RFC 6335](https://tools.ietf.org/html/rfc6335))
- **Time-to-Live (TTL)**: `1` (as recommended by
  [RFC 1112 Section 6.1](https://tools.ietf.org/html/rfc1112#section-6.1)
  ; messages do not leave the local network)

## Security Considerations

In the realm of network communication, security is paramount. When using multicast communication,
be vigilant about potential vulnerabilities:

- **Data Sanitization**: Always sanitize incoming data to prevent injection attacks
  ([CWE-20](https://cwe.mitre.org/data/definitions/20.html),
  [CWE-74](https://cwe.mitre.org/data/definitions/74.html)).

- **Network Scope**: Be mindful of the TTL settings to limit message propagation to the intended
  network segment. Inappropriate TTL values might expose your multicast traffic beyond the local
  network, potentially leading to information disclosure
  ([CWE-200](https://cwe.mitre.org/data/definitions/200.html)).

- **Validation and Error Handling**: Implement robust validation and error handling to prevent
  misuse or disruption of multicast services.
  ([CWE-351](https://cwe.mitre.org/data/definitions/351.html)).

As Bruce Schneier aptly puts it, "Security is a process, not a product." Always be proactive in
assessing and mitigating risks in your implementations and use of `multicast`.

[![OpenSSF Best Practices](https://www.bestpractices.dev/projects/9458/badge)](https://www.bestpractices.dev/projects/9458)

## Documentation

For more detailed documentation and advanced usage, please refer to the
[official documentation](https://reactive-firewallmulticast.readthedocs.io/en/master/).

## Contributing

Contributions are welcome! Please read the
[contributing guidelines](https://github.com/reactive-firewall/multicast/blob/stable/.github/CONTRIBUTING)
for more information.

### Next steps

Next-steps and bug-fixes are tracked [Here](https://github.com/users/reactive-firewall/projects/1).

## License

### Copyright (c) 2021-2025, Mr. Walls

This project is licensed under the MIT License. See the
[LICENSE.md](https://github.com/reactive-firewall/multicast/blob/stable/LICENSE.md) file for
details.

[![License - MIT](https://img.shields.io/pypi/l/multicast?cacheSeconds=3600)](https://github.com/reactive-firewall/multicast/blob/stable/LICENSE.md)
