Skip to content

Commit bfa218f

Browse files
Copilothyp3ri0n-ng
Copilot
and
hyp3ri0n-ng
committed
Add missing documentation files and update README
Co-authored-by: hyp3ri0n-ng <3106718+hyp3ri0n-ng@users.noreply.github.com>
1 parent 3cb8a5b commit bfa218f

File tree

6 files changed

+396
-4
lines changed

6 files changed

+396
-4
lines changed

‎CHANGELOG.md‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
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+
- CODE_OF_CONDUCT.md following Contributor Covenant
13+
- SECURITY.md with security policy
14+
- This CHANGELOG.md file
15+
16+
## [0.5.0] - 2023
17+
18+
### Added
19+
- I/O Mode: New `cdp.connection` module with WebSocket I/O support
20+
- WebSocket management with async context managers
21+
- JSON-RPC message framing
22+
- Command multiplexing
23+
- Event handling with async iterators
24+
- Comprehensive error handling with typed exceptions
25+
26+
### Changed
27+
- Enhanced documentation with I/O mode examples
28+
- Updated README with usage for both Sans-I/O and I/O modes
29+
30+
## [0.4.x and earlier]
31+
32+
### Features
33+
- Sans-I/O mode with type wrappers for Chrome DevTools Protocol
34+
- Auto-generated Python bindings from CDP specification
35+
- Type hints for all CDP commands, events, and types
36+
- Support for all CDP domains
37+
- Documentation on ReadTheDocs
38+
- Example scripts demonstrating CDP usage
39+
40+
---
41+
42+
For a complete list of changes, see the [commit history](https://github.com/HyperionGray/python-chrome-devtools-protocol/commits/master).
43+
44+
[Unreleased]: https://github.com/HyperionGray/python-chrome-devtools-protocol/compare/v0.5.0...HEAD
45+
[0.5.0]: https://github.com/HyperionGray/python-chrome-devtools-protocol/releases/tag/v0.5.0

‎CODE_OF_CONDUCT.md‎

Lines changed: 128 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,128 @@
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's
63+
GitHub repository by opening an issue. All complaints will be reviewed and
64+
investigated promptly and fairly.
65+
66+
All community leaders are obligated to respect the privacy and security of the
67+
reporter of any incident.
68+
69+
## Enforcement Guidelines
70+
71+
Community leaders will follow these Community Impact Guidelines in determining
72+
the consequences for any action they deem in violation of this Code of Conduct:
73+
74+
### 1. Correction
75+
76+
**Community Impact**: Use of inappropriate language or other behavior deemed
77+
unprofessional or unwelcome in the community.
78+
79+
**Consequence**: A private, written warning from community leaders, providing
80+
clarity around the nature of the violation and an explanation of why the
81+
behavior was inappropriate. A public apology may be requested.
82+
83+
### 2. Warning
84+
85+
**Community Impact**: A violation through a single incident or series
86+
of actions.
87+
88+
**Consequence**: A warning with consequences for continued behavior. No
89+
interaction with the people involved, including unsolicited interaction with
90+
those enforcing the Code of Conduct, for a specified period of time. This
91+
includes avoiding interactions in community spaces as well as external channels
92+
like social media. Violating these terms may lead to a temporary or
93+
permanent ban.
94+
95+
### 3. Temporary Ban
96+
97+
**Community Impact**: A serious violation of community standards, including
98+
sustained inappropriate behavior.
99+
100+
**Consequence**: A temporary ban from any sort of interaction or public
101+
communication with the community for a specified period of time. No public or
102+
private interaction with the people involved, including unsolicited interaction
103+
with those enforcing the Code of Conduct, is allowed during this period.
104+
Violating these terms may lead to a permanent ban.
105+
106+
### 4. Permanent Ban
107+
108+
**Community Impact**: Demonstrating a pattern of violation of community
109+
standards, including sustained inappropriate behavior, harassment of an
110+
individual, or aggression toward or disparagement of classes of individuals.
111+
112+
**Consequence**: A permanent ban from any sort of public interaction within
113+
the community.
114+
115+
## Attribution
116+
117+
This Code of Conduct is adapted from the [Contributor Covenant][homepage],
118+
version 2.0, available at
119+
https://www.contributor-covenant.org/version/2/0/code_of_conduct.html.
120+
121+
Community Impact Guidelines were inspired by [Mozilla's code of conduct
122+
enforcement ladder](https://github.com/mozilla/diversity).
123+
124+
[homepage]: https://www.contributor-covenant.org
125+
126+
For answers to common questions about this code of conduct, see the FAQ at
127+
https://www.contributor-covenant.org/faq. Translations are available at
128+
https://www.contributor-covenant.org/translations.

‎CONTRIBUTING.md‎

Lines changed: 108 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,108 @@
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+
## Code of Conduct
6+
7+
By participating in this project, you agree to abide by our Code of Conduct (see [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md)).
8+
9+
## How to Contribute
10+
11+
### Reporting Bugs
12+
13+
If you find a bug, please open an issue on GitHub with:
14+
- A clear description of the problem
15+
- Steps to reproduce the issue
16+
- Expected vs. actual behavior
17+
- Your environment (OS, Python version, etc.)
18+
19+
### Suggesting Enhancements
20+
21+
Enhancement suggestions are welcome! Please open an issue describing:
22+
- The enhancement you'd like to see
23+
- Why it would be useful
24+
- Any implementation ideas you have
25+
26+
### Pull Requests
27+
28+
1. **Fork the repository** and create your branch from `master`
29+
2. **Install development dependencies**:
30+
```bash
31+
pip install poetry
32+
poetry install
33+
```
34+
3. **Make your changes** following the project's coding standards
35+
4. **Run tests** to ensure nothing is broken:
36+
```bash
37+
poetry run make
38+
```
39+
5. **Update documentation** if needed
40+
6. **Commit your changes** with clear, descriptive commit messages
41+
7. **Push to your fork** and submit a pull request
42+
43+
## Development Setup
44+
45+
### Prerequisites
46+
47+
- Python 3.7 or higher
48+
- Poetry for dependency management
49+
50+
### Installation
51+
52+
```bash
53+
# Clone the repository
54+
git clone https://github.com/HyperionGray/python-chrome-devtools-protocol.git
55+
cd python-chrome-devtools-protocol
56+
57+
# Install dependencies
58+
poetry install
59+
```
60+
61+
### Running Tests
62+
63+
```bash
64+
# Run all tests
65+
poetry run make
66+
67+
# Run specific test suites
68+
poetry run pytest test/
69+
poetry run pytest generator/
70+
71+
# Run type checking
72+
poetry run mypy cdp/
73+
poetry run mypy generator/
74+
```
75+
76+
### Code Generation
77+
78+
This project generates Python code from the Chrome DevTools Protocol specification:
79+
80+
```bash
81+
poetry run python generator/generate.py
82+
```
83+
84+
The generated code is checked into version control. If you modify the generator, run it and include the updated generated files in your PR.
85+
86+
## Coding Standards
87+
88+
- Follow [PEP 8](https://www.python.org/dev/peps/pep-0008/) style guidelines
89+
- Use type hints for all functions and methods
90+
- Write docstrings for public APIs
91+
- Ensure code passes `mypy` type checking
92+
- Keep code coverage high
93+
94+
## Project Structure
95+
96+
- `cdp/` - Generated CDP protocol bindings
97+
- `generator/` - Code generator for CDP bindings
98+
- `test/` - Test suite
99+
- `docs/` - Documentation source files
100+
- `examples/` - Example usage scripts
101+
102+
## Questions?
103+
104+
If you have questions about contributing, feel free to open an issue or reach out to the maintainers.
105+
106+
## License
107+
108+
By contributing to PyCDP, you agree that your contributions will be licensed under the MIT License.

‎LICENSE.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
LICENSE

‎README.md‎

Lines changed: 37 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -79,10 +79,6 @@ 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

@@ -92,4 +88,41 @@ assert repr(frame_id) == "FrameId('my id')"
9288

9389
For more information, see the [complete documentation](https://py-cdp.readthedocs.io).
9490

91+
## API Reference
92+
93+
The library provides Python wrappers for all Chrome DevTools Protocol domains:
94+
95+
- **Page**: Page control (navigation, screenshots, etc.)
96+
- **DOM**: DOM inspection and manipulation
97+
- **Network**: Network monitoring and interception
98+
- **Runtime**: JavaScript execution and evaluation
99+
- **Debugger**: JavaScript debugging
100+
- **Performance**: Performance metrics and profiling
101+
- **Security**: Security-related information
102+
- And many more...
103+
104+
For complete API documentation, visit [py-cdp.readthedocs.io](https://py-cdp.readthedocs.io).
105+
106+
### Type System
107+
108+
All CDP types, commands, and events are fully typed with Python type hints, providing:
109+
- IDE autocomplete support
110+
- Static type checking with mypy
111+
- Clear API contracts
112+
- Inline documentation
113+
114+
## Contributing
115+
116+
We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details on:
117+
- How to report bugs and request features
118+
- Development setup and workflow
119+
- Coding standards and testing requirements
120+
- Pull request process
121+
122+
For questions or discussions, feel free to open an issue on GitHub.
123+
124+
## License
125+
126+
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
127+
95128
<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)