Skip to content

Commit fbd2d79

Browse files
Copilothyp3ri0n-ng
Copilot
and
hyp3ri0n-ng
committed
Add missing documentation files and README sections
Co-authored-by: hyp3ri0n-ng <3106718+hyp3ri0n-ng@users.noreply.github.com>
1 parent 4e6292b commit fbd2d79

File tree

5 files changed

+504
-5
lines changed

5 files changed

+504
-5
lines changed

‎CHANGELOG.md‎

Lines changed: 72 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,72 @@
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+
## [Unreleased]
9+
10+
### Added
11+
- CONTRIBUTING.md with contribution guidelines
12+
- CHANGELOG.md for tracking version history
13+
- CODE_OF_CONDUCT.md for community standards
14+
- SECURITY.md with security policy and vulnerability reporting
15+
16+
## [0.5.0] - 2024
17+
18+
### Added
19+
- I/O Mode with built-in WebSocket connection support via `cdp.connection` module
20+
- WebSocket management with async context managers
21+
- JSON-RPC message framing and multiplexing
22+
- Event handling via async iterators
23+
- Comprehensive error handling with typed exceptions
24+
- Optional websockets dependency via `[io]` extra
25+
26+
### Changed
27+
- Enhanced README with I/O mode documentation
28+
- Improved examples demonstrating both Sans-I/O and I/O modes
29+
30+
## [0.4.0] - 2023
31+
32+
### Changed
33+
- Updated to latest Chrome DevTools Protocol specification
34+
- Improved type hints and mypy compliance
35+
- Enhanced documentation
36+
37+
## [0.3.0] - 2022
38+
39+
### Added
40+
- Initial Sans-I/O implementation
41+
- Automatic code generation from CDP specification
42+
- Type wrappers for all CDP types, commands, and events
43+
- Comprehensive test suite
44+
45+
### Changed
46+
- Improved project structure
47+
- Enhanced type safety
48+
49+
## [0.2.0] - 2021
50+
51+
### Added
52+
- Enhanced type definitions
53+
- Additional protocol domains
54+
55+
### Fixed
56+
- Various type annotation improvements
57+
- Bug fixes in code generation
58+
59+
## [0.1.0] - 2018
60+
61+
### Added
62+
- Initial release
63+
- Basic type wrappers for Chrome DevTools Protocol
64+
- Code generator from CDP specification
65+
- MIT License
66+
67+
[Unreleased]: https://github.com/HyperionGray/python-chrome-devtools-protocol/compare/v0.5.0...HEAD
68+
[0.5.0]: https://github.com/HyperionGray/python-chrome-devtools-protocol/compare/v0.4.0...v0.5.0
69+
[0.4.0]: https://github.com/HyperionGray/python-chrome-devtools-protocol/compare/v0.3.0...v0.4.0
70+
[0.3.0]: https://github.com/HyperionGray/python-chrome-devtools-protocol/compare/v0.2.0...v0.3.0
71+
[0.2.0]: https://github.com/HyperionGray/python-chrome-devtools-protocol/compare/v0.1.0...v0.2.0
72+
[0.1.0]: https://github.com/HyperionGray/python-chrome-devtools-protocol/releases/tag/v0.1.0

‎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 via GitHub issues.
63+
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: 138 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,138 @@
1+
# Contributing to PyCDP
2+
3+
Thank you for your interest in contributing to Python Chrome DevTools Protocol (PyCDP)! We welcome contributions from the community.
4+
5+
## Getting Started
6+
7+
### Prerequisites
8+
9+
- Python 3.7 or higher
10+
- Poetry for dependency management
11+
- Git for version control
12+
13+
### Setting Up Development Environment
14+
15+
1. Fork and clone the repository:
16+
```bash
17+
git clone https://github.com/YOUR_USERNAME/python-chrome-devtools-protocol.git
18+
cd python-chrome-devtools-protocol
19+
```
20+
21+
2. Install dependencies:
22+
```bash
23+
pip install poetry
24+
poetry install
25+
```
26+
27+
## Development Workflow
28+
29+
### Code Generation
30+
31+
This project automatically generates Python wrappers from the Chrome DevTools Protocol specification:
32+
33+
```bash
34+
poetry run python generator/generate.py
35+
```
36+
37+
### Running Tests
38+
39+
Run the test suite:
40+
```bash
41+
poetry run pytest test/
42+
poetry run pytest generator/
43+
```
44+
45+
### Type Checking
46+
47+
We use mypy for static type checking:
48+
```bash
49+
poetry run mypy cdp/
50+
poetry run mypy generator/
51+
```
52+
53+
### Complete Build
54+
55+
Run all checks (type checking, tests, and generation):
56+
```bash
57+
poetry run make default
58+
```
59+
60+
## Submitting Changes
61+
62+
### Pull Request Process
63+
64+
1. Create a new branch for your feature or bugfix:
65+
```bash
66+
git checkout -b feature/your-feature-name
67+
```
68+
69+
2. Make your changes and ensure:
70+
- All tests pass
71+
- Code passes type checking
72+
- Code follows the existing style
73+
- Documentation is updated if needed
74+
75+
3. Commit your changes with clear, descriptive messages:
76+
```bash
77+
git commit -m "Add feature: brief description"
78+
```
79+
80+
4. Push to your fork and submit a pull request:
81+
```bash
82+
git push origin feature/your-feature-name
83+
```
84+
85+
5. In your pull request description:
86+
- Describe what changes you made and why
87+
- Reference any related issues
88+
- Include any relevant context
89+
90+
### Code Review
91+
92+
- Maintainers will review your pull request
93+
- Address any feedback or requested changes
94+
- Once approved, a maintainer will merge your PR
95+
96+
## Reporting Issues
97+
98+
### Bug Reports
99+
100+
When reporting bugs, please include:
101+
- A clear, descriptive title
102+
- Steps to reproduce the issue
103+
- Expected behavior vs. actual behavior
104+
- Python version and environment details
105+
- Any relevant error messages or logs
106+
107+
### Feature Requests
108+
109+
For feature requests, please:
110+
- Clearly describe the feature and its use case
111+
- Explain why it would be valuable
112+
- Provide examples if possible
113+
114+
## Code Style
115+
116+
- Follow PEP 8 style guidelines
117+
- Use type hints for function parameters and return values
118+
- Write clear, descriptive variable and function names
119+
- Add docstrings for public APIs
120+
- Keep functions focused and modular
121+
122+
## Documentation
123+
124+
- Update README.md if you add new features
125+
- Update docstrings for any modified functions or classes
126+
- Add examples for new functionality when appropriate
127+
128+
## License
129+
130+
By contributing, you agree that your contributions will be licensed under the MIT License.
131+
132+
## Questions?
133+
134+
If you have questions, feel free to:
135+
- Open an issue for discussion
136+
- Reach out to the maintainers
137+
138+
Thank you for contributing to PyCDP!

‎README.md‎

Lines changed: 28 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -79,17 +79,40 @@ See the [examples directory](examples/) for more usage patterns.
7979

8080
For users who prefer to manage their own I/O:
8181

82-
## Sans-I/O Mode (Original)
83-
84-
For users who prefer to manage their own I/O:
85-
8682
```python
8783
from cdp import page
8884

8985
frame_id = page.FrameId('my id')
9086
assert repr(frame_id) == "FrameId('my id')"
9187
```
9288

93-
For more information, see the [complete documentation](https://py-cdp.readthedocs.io).
89+
## API Documentation
90+
91+
For detailed API documentation, see:
92+
93+
- **[Complete Documentation](https://py-cdp.readthedocs.io)** - Full API reference on Read the Docs
94+
- **[Chrome DevTools Protocol](https://chromedevtools.github.io/devtools-protocol/)** - Official CDP specification
95+
- **[Examples](examples/)** - Code examples demonstrating usage patterns
96+
97+
### Key Modules
98+
99+
- `cdp.connection` - WebSocket I/O and connection management (I/O mode)
100+
- `cdp.<domain>` - Type wrappers for each CDP domain (e.g., `cdp.page`, `cdp.network`, `cdp.runtime`)
101+
- Each domain module provides types, commands, and events for that CDP domain
102+
103+
## Contributing
104+
105+
We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details on:
106+
107+
- Setting up your development environment
108+
- Running tests and type checking
109+
- Submitting pull requests
110+
- Reporting issues
111+
112+
Please also read our [Code of Conduct](CODE_OF_CONDUCT.md) before contributing.
113+
114+
## Security
115+
116+
For information about reporting security vulnerabilities, please see our [Security Policy](SECURITY.md).
94117

95118
<a href="https://www.hyperiongray.com/?pk_campaign=github&pk_kwd=pycdp"><img alt="define hyperion gray" width="500px" src="https://hyperiongray.s3.amazonaws.com/define-hg.svg"></a>

0 commit comments

Comments
 (0)