Skip to content

Commit f568b06

Browse files
Copilothyp3ri0n-ng
Copilot
and
hyp3ri0n-ng
committed
Add essential documentation files and enhance README
- Add CONTRIBUTING.md with development guidelines - Add CHANGELOG.md with version history and migration guides - Add CODE_OF_CONDUCT.md (Contributor Covenant v2.0) - Rename SECURITY_UPDATES.md to SECURITY.md (GitHub standard) - Enhance README.md with comprehensive API reference section - Fix duplicate "Sans-I/O Mode" section in README - Add Contributing, Security, and Changelog links to README - Enhance .gitignore with comprehensive Python artifact exclusions Co-authored-by: hyp3ri0n-ng <3106718+hyp3ri0n-ng@users.noreply.github.com>
1 parent 90b4e46 commit f568b06

File tree

6 files changed

+426
-4
lines changed

6 files changed

+426
-4
lines changed

‎.gitignore‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,3 +8,21 @@ build
88
dist
99
docs/_build
1010
venv
11+
*.pyc
12+
*.pyo
13+
*.pyd
14+
.Python
15+
env/
16+
ENV/
17+
.env
18+
.venv
19+
pip-log.txt
20+
pip-delete-this-directory.txt
21+
.coverage
22+
htmlcov/
23+
.tox/
24+
.hypothesis/
25+
*.egg
26+
.eggs/
27+
*.log
28+
.DS_Store

‎CHANGELOG.md‎

Lines changed: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
# Changelog
2+
3+
All notable changes to this project will be documented in this file.
4+
5+
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
6+
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7+
8+
## [0.5.0] - 2024-12-XX
9+
10+
### Added
11+
- **I/O Mode**: New `cdp.connection` module providing WebSocket I/O, JSON-RPC framing, and command multiplexing
12+
- **8 New Domains**: Extensions, FedCm, DeviceAccess, FileSystem, Autofill, BluetoothEmulation, PWA, Preload
13+
- **Privacy Sandbox APIs**: Comprehensive support for Attribution Reporting, Shared Storage, Interest Groups/FLEDGE
14+
- Security-focused APIs for testing federated authentication, device permissions, and extension boundaries
15+
- Bounce tracking mitigation testing capabilities
16+
- IP protection proxy status and control
17+
- Related Website Sets (First-Party Sets) support
18+
- Form security issue detection via Audits domain
19+
- Privacy Sandbox enrollment override for testing
20+
- Enhanced cookie controls for third-party cookie testing
21+
22+
### Changed
23+
- Updated to Chrome DevTools Protocol version 1.3 (latest)
24+
- Fixed same-domain type reference bug in code generator (e.g., `Network.TimeSinceEpoch` now correctly resolves)
25+
- Improved code generator to protect manually-written files (connection.py, util.py)
26+
- `page.navigate()` now returns 4 values instead of 3 (added `is_download` parameter)
27+
28+
### Removed
29+
- **Breaking Change**: Removed deprecated Database domain (use IndexedDB, Storage, or Cache Storage APIs instead)
30+
31+
### Security
32+
- Added comprehensive security testing capabilities for Privacy Sandbox
33+
- Enhanced storage domain with privacy-preserving measurement APIs
34+
- Added attribution reporting and shared storage tracking
35+
- Improved form security auditing
36+
37+
## [0.4.0] - Previous Release
38+
39+
### Added
40+
- Initial sans-I/O implementation
41+
- Type wrappers for Chrome DevTools Protocol
42+
- Automatic code generation from CDP specification
43+
- Support for Python 3.7+
44+
45+
## Migration Guide
46+
47+
### From 0.4.x to 0.5.0
48+
49+
#### Database Domain Removed
50+
```python
51+
# Old (no longer works)
52+
from cdp import database
53+
await conn.execute(database.some_command())
54+
55+
# New - Use IndexedDB instead
56+
from cdp import indexed_db
57+
await conn.execute(indexed_db.request_database_names(security_origin="https://example.com"))
58+
```
59+
60+
#### page.navigate() Return Signature Changed
61+
```python
62+
# Old (3 values)
63+
frame_id, loader_id, error_text = await conn.execute(page.navigate(url="..."))
64+
65+
# New (4 values - added is_download)
66+
frame_id, loader_id, error_text, is_download = await conn.execute(page.navigate(url="..."))
67+
```
68+
69+
## Links
70+
71+
- [Repository](https://github.com/HyperionGray/python-chrome-devtools-protocol)
72+
- [Documentation](https://py-cdp.readthedocs.io)
73+
- [PyPI](https://pypi.org/project/chrome-devtools-protocol/)
74+
- [Chrome DevTools Protocol](https://chromedevtools.github.io/devtools-protocol/)
75+
76+
---
77+
78+
For detailed security-relevant updates, see [SECURITY.md](SECURITY.md).
79+
For implementation details, see [IMPLEMENTATION.md](IMPLEMENTATION.md).

‎CODE_OF_CONDUCT.md‎

Lines changed: 127 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,127 @@
1+
# Contributor Covenant Code of Conduct
2+
3+
## Our Pledge
4+
5+
We as members, contributors, and leaders pledge to make participation in our
6+
community a harassment-free experience for everyone, regardless of age, body
7+
size, visible or invisible disability, ethnicity, sex characteristics, gender
8+
identity and expression, level of experience, education, socio-economic status,
9+
nationality, personal appearance, race, religion, or sexual identity
10+
and orientation.
11+
12+
We pledge to act and interact in ways that contribute to an open, welcoming,
13+
diverse, inclusive, and healthy community.
14+
15+
## Our Standards
16+
17+
Examples of behavior that contributes to a positive environment for our
18+
community include:
19+
20+
* Demonstrating empathy and kindness toward other people
21+
* Being respectful of differing opinions, viewpoints, and experiences
22+
* Giving and gracefully accepting constructive feedback
23+
* Accepting responsibility and apologizing to those affected by our mistakes,
24+
and learning from the experience
25+
* Focusing on what is best not just for us as individuals, but for the
26+
overall community
27+
28+
Examples of unacceptable behavior include:
29+
30+
* The use of sexualized language or imagery, and sexual attention or
31+
advances of any kind
32+
* Trolling, insulting or derogatory comments, and personal or political attacks
33+
* Public or private harassment
34+
* Publishing others' private information, such as a physical or email
35+
address, without their explicit permission
36+
* Other conduct which could reasonably be considered inappropriate in a
37+
professional setting
38+
39+
## Enforcement Responsibilities
40+
41+
Community leaders are responsible for clarifying and enforcing our standards of
42+
acceptable behavior and will take appropriate and fair corrective action in
43+
response to any behavior that they deem inappropriate, threatening, offensive,
44+
or harmful.
45+
46+
Community leaders have the right and responsibility to remove, edit, or reject
47+
comments, commits, code, wiki edits, issues, and other contributions that are
48+
not aligned to this Code of Conduct, and will communicate reasons for moderation
49+
decisions when appropriate.
50+
51+
## Scope
52+
53+
This Code of Conduct applies within all community spaces, and also applies when
54+
an individual is officially representing the community in public spaces.
55+
Examples of representing our community include using an official e-mail address,
56+
posting via an official social media account, or acting as an appointed
57+
representative at an online or offline event.
58+
59+
## Enforcement
60+
61+
Instances of abusive, harassing, or otherwise unacceptable behavior may be
62+
reported to the community leaders responsible for enforcement at the project
63+
repository. All complaints will be reviewed and investigated promptly and fairly.
64+
65+
All community leaders are obligated to respect the privacy and security of the
66+
reporter of any incident.
67+
68+
## Enforcement Guidelines
69+
70+
Community leaders will follow these Community Impact Guidelines in determining
71+
the consequences for any action they deem in violation of this Code of Conduct:
72+
73+
### 1. Correction
74+
75+
**Community Impact**: Use of inappropriate language or other behavior deemed
76+
unprofessional or unwelcome in the community.
77+
78+
**Consequence**: A private, written warning from community leaders, providing
79+
clarity around the nature of the violation and an explanation of why the
80+
behavior was inappropriate. A public apology may be requested.
81+
82+
### 2. Warning
83+
84+
**Community Impact**: A violation through a single incident or series
85+
of actions.
86+
87+
**Consequence**: A warning with consequences for continued behavior. No
88+
interaction with the people involved, including unsolicited interaction with
89+
those enforcing the Code of Conduct, for a specified period of time. This
90+
includes avoiding interactions in community spaces as well as external channels
91+
like social media. Violating these terms may lead to a temporary or
92+
permanent ban.
93+
94+
### 3. Temporary Ban
95+
96+
**Community Impact**: A serious violation of community standards, including
97+
sustained inappropriate behavior.
98+
99+
**Consequence**: A temporary ban from any sort of interaction or public
100+
communication with the community for a specified period of time. No public or
101+
private interaction with the people involved, including unsolicited interaction
102+
with those enforcing the Code of Conduct, is allowed during this period.
103+
Violating these terms may lead to a permanent ban.
104+
105+
### 4. Permanent Ban
106+
107+
**Community Impact**: Demonstrating a pattern of violation of community
108+
standards, including sustained inappropriate behavior, harassment of an
109+
individual, or aggression toward or disparagement of classes of individuals.
110+
111+
**Consequence**: A permanent ban from any sort of public interaction within
112+
the community.
113+
114+
## Attribution
115+
116+
This Code of Conduct is adapted from the [Contributor Covenant][homepage],
117+
version 2.0, available at
118+
https://www.contributor-covenant.org/version/2/0/code_of_conduct.html.
119+
120+
Community Impact Guidelines were inspired by [Mozilla's code of conduct
121+
enforcement ladder](https://github.com/mozilla/diversity).
122+
123+
[homepage]: https://www.contributor-covenant.org
124+
125+
For answers to common questions about this code of conduct, see the FAQ at
126+
https://www.contributor-covenant.org/faq. Translations are available at
127+
https://www.contributor-covenant.org/translations.

‎CONTRIBUTING.md‎

Lines changed: 143 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,143 @@
1+
# Contributing to PyCDP
2+
3+
Thank you for your interest in contributing to Python Chrome DevTools Protocol (PyCDP)! This document provides guidelines for contributing to the project.
4+
5+
## Getting Started
6+
7+
### Prerequisites
8+
9+
- Python 3.7 or higher
10+
- [Poetry](https://python-poetry.org/) for dependency management
11+
12+
### Setting Up Your Development Environment
13+
14+
1. Fork the repository on GitHub
15+
2. Clone your fork locally:
16+
```bash
17+
git clone https://github.com/YOUR_USERNAME/python-chrome-devtools-protocol.git
18+
cd python-chrome-devtools-protocol
19+
```
20+
3. Install dependencies:
21+
```bash
22+
poetry install
23+
```
24+
25+
## Development Workflow
26+
27+
### Code Generation
28+
29+
This project automatically generates Python wrappers from the Chrome DevTools Protocol specification. Most code in the `cdp/` directory (except `connection.py` and `util.py`) is auto-generated.
30+
31+
To regenerate the protocol wrappers:
32+
```bash
33+
poetry run make generate
34+
```
35+
36+
### Running Tests
37+
38+
Run the test suite:
39+
```bash
40+
poetry run make test-cdp
41+
poetry run make test-generate
42+
```
43+
44+
Or run all checks:
45+
```bash
46+
poetry run make
47+
```
48+
49+
### Type Checking
50+
51+
We use mypy for static type checking:
52+
```bash
53+
poetry run make mypy-cdp
54+
poetry run make mypy-generate
55+
```
56+
57+
### Building Documentation
58+
59+
To build the documentation:
60+
```bash
61+
poetry run make docs
62+
```
63+
64+
## Making Changes
65+
66+
### Code Style
67+
68+
- Follow PEP 8 style guidelines
69+
- Use type hints for all function signatures
70+
- Keep code clear and well-documented
71+
72+
### Commit Messages
73+
74+
- Use clear and descriptive commit messages
75+
- Reference issue numbers when applicable
76+
- Keep commits focused on a single change
77+
78+
### Pull Requests
79+
80+
1. Create a new branch for your changes:
81+
```bash
82+
git checkout -b feature/your-feature-name
83+
```
84+
2. Make your changes and commit them
85+
3. Push to your fork and submit a pull request
86+
4. Ensure all tests pass and type checking succeeds
87+
5. Provide a clear description of your changes
88+
89+
## What to Contribute
90+
91+
### Areas for Contribution
92+
93+
- **Bug fixes**: Fix issues in the connection module or utility functions
94+
- **Documentation**: Improve examples, tutorials, or API documentation
95+
- **Tests**: Add test coverage for existing functionality
96+
- **Examples**: Add new usage examples in the `examples/` directory
97+
98+
### Code Generation Changes
99+
100+
If you need to modify code generation:
101+
- Edit files in the `generator/` directory
102+
- Run the generator and verify the output
103+
- Ensure all tests still pass
104+
- Add tests for your generator changes
105+
106+
### Protocol Updates
107+
108+
The protocol definitions are automatically fetched from the Chrome DevTools Protocol repository. If you need to update to a newer protocol version, please open an issue first to discuss the change.
109+
110+
## Reporting Issues
111+
112+
### Bug Reports
113+
114+
When reporting bugs, please include:
115+
- Python version
116+
- PyCDP version
117+
- Steps to reproduce
118+
- Expected vs. actual behavior
119+
- Error messages or stack traces
120+
121+
### Feature Requests
122+
123+
For feature requests:
124+
- Clearly describe the feature
125+
- Explain the use case
126+
- Consider if it fits the project's scope
127+
128+
## Code of Conduct
129+
130+
Please be respectful and constructive in all interactions. We are committed to providing a welcoming and inclusive environment for all contributors.
131+
132+
## Questions?
133+
134+
If you have questions about contributing, please:
135+
- Check existing issues and pull requests
136+
- Open a new issue with your question
137+
- Tag it appropriately for visibility
138+
139+
## License
140+
141+
By contributing to PyCDP, you agree that your contributions will be licensed under the MIT License.
142+
143+
Thank you for contributing to PyCDP!

0 commit comments

Comments
 (0)