Merge pull request #122 from hbisneto/stage

FileSystemPro 3.0.0.0

Author: hbisneto

.gitignore

@@ -1,5 +1,3 @@
-app.py
-
 # Byte-compiled / optimized / DLL files
 __pycache__/
 *.py[cod]

CODE_OF_CONDUCT.md

@@ -0,0 +1,73 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, religion, or sexual identity and orientation.
+
+We pledge to act and speak in a way that makes a safe, welcoming, and inclusive community for all.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility for our own speech and our own actions
+* Participating in every discussion and decision of our community, either:
+
+  * Positively contributing, or without disrupting the conversation
+  * Choosing to politely excuse ourselves from conversations
+
+* Focusing on what is best not just for us as individuals, but for the
+  overall community and the project
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or
+  advances of any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email
+  address, without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of acceptable behavior and will take appropriate and fair corrective action in response to any behavior that they deem inappropriate, threatening, offensive, or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, and will communicate reasons for moderation decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when an individual is officially representing the community in public spaces. Examples of representing our community include using an official e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the community leaders responsible for enforcement at [[email protected]](mailto:[email protected]). All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders are responsible for enforcing the Code of Conduct. They will follow our [enforcement guidelines](https://github.com/hbisneto/FileSystemPro/blob/main/ENFORCEMENT.md) which include:
+
+- **Documenting Incidents**: Log all reports and actions taken.
+- **Confidentiality**: Keep reports private unless explicit permission.
+- **Escalation**: For severe cases, involve legal counsel or authorities if needed.
+- **No Retaliation**: Protect reporters from backlash.
+- **Appeals**: Allow moderated parties to appeal decisions.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant, version 2.1](https://www.contributor-covenant.org/version/2/1/code_of_conduct/), available at https://www.contributor-covenant.org/version/2/1/code_of_conduct.html.
+
+Specific customizations for FileSystemPro:
+
+- Contact email: [[email protected]](mailto:[email protected]) for reports.
+- Enforcement link: Points to a custom [ENFORCEMENT.md](https://github.com/hbisneto/FileSystemPro/blob/main/ENFORCEMENT.md) (create this if needed for detailed procedures).
+
+Community Impact Guidelines were created by [Molly de Blanc](https://github.com/mollydb) and adapted from the [Citizen Code of Conduct](https://github.com/stumpsyn/policies/blob/master/citizen_code_of_conduct.md) by Richard Matthew Cornwell.
+
+For answers to common questions about this code of conduct, see the FAQ at https://www.contributor-covenant.org/faq. Translations are available at https://www.contributor-covenant.org/translations.

CONTRIBUTING.md

@@ -0,0 +1,130 @@
+# Contributing to FileSystemPro
+
+Thank you for considering contributing to **FileSystemPro**! We appreciate your interest in improving this cross-platform file system toolkit. Whether it's fixing bugs, adding features, enhancing documentation, or refining code, your contributions help make the library more robust and user-friendly.
+
+Before starting, please read this guide to understand our contribution process. By participating, you agree to abide by our [Code of Conduct](https://github.com/hbisneto/FileSystemPro/blob/main/CODE_OF_CONDUCT.md).
+
+## Code of Conduct
+
+We follow the [Contributor Covenant Code of Conduct](https://www.contributor-covenant.org/version/2/1/code_of_conduct/). All contributors are expected to uphold this standard. If you encounter issues, contact us at [[email protected]](mailto:[email protected]) or via GitHub issues.
+
+## Ways to Contribute
+
+We welcome all kinds of contributions! Here are some ideas:
+
+- **Bug Reports**: Found an issue? [Open an issue](https://github.com/hbisneto/FileSystemPro/issues/new) with a clear description, steps to reproduce, and environment details (OS, Python version, `psutil` if used).
+- **Feature Requests**: Have an idea? [Suggest it here](https://github.com/hbisneto/FileSystemPro/issues/new?template=feature_request.md). Include use cases and rationale.
+- **Documentation**: Typos, clarifications, or new examples? Edit READMEs or submodule docs directly via PR.
+- **Code**: Implement features, fix bugs, or refactor. See below for details.
+- **Tests**: Add or improve tests in `tests/`.
+- **Other**: Translations, performance benchmarks, or tooling scripts.
+
+## Development Setup
+
+1. **Fork and Clone**:
+
+   ```bash
+   git clone https://github.com/YOUR_USERNAME/FileSystemPro.git
+   cd FileSystemPro
+   git remote add upstream https://github.com/hbisneto/FileSystemPro.git
+   ```
+
+2. **Virtual Environment**:
+
+   ```bash
+   python -m venv .venv
+   source .venv/bin/activate  # On Unix/macOS
+   # Or: .venv\Scripts\activate  # On Windows
+   ```
+
+3. **Install Dependencies**:
+
+   ```bash
+   pip install -e .[dev]  # Editable install + dev extras (pytest, black, flake8)
+   pip install psutil     # Optional, for device module
+   ```
+
+4. **Verify Setup**:
+
+   ```bash
+   pytest tests/          # Run tests
+   black --check .        # Check formatting
+   flake8 .               # Lint
+   ```
+
+## Coding Standards
+
+- **Python Version**: Target 3.10+; test on 3.10, 3.12.
+- **Style Guide**: Follow [PEP 8](https://peps.python.org/pep-0008/). Use [Black](https://black.readthedocs.io/) for formatting:
+  ```bash
+  black .
+  ```
+- **Linting**: [Flake8](https://flake8.pycqa.org/) for style checks:
+  ```bash
+  flake8 .
+  ```
+- **Type Hints**: Use [mypy](https://mypy-lang.org/) where practical (not enforced yet).
+- **Docstrings**: [Google style](https://google.github.io/styleguide/pyguide.html#38-comments-and-docstrings) for functions/classes.
+- **Commit Messages**: Conventional commits (e.g., `feat: add network monitoring`).
+- **Branches**: Feature branches from `main` (e.g., `feat/new-module`).
+
+## Making a Contribution
+
+1. **Discuss First**: For non-trivial changes, open an issue to align on scope.
+
+2. **Branch and Commit**:
+
+   ```bash
+   git checkout -b your-branch-name
+   git add .
+   git commit -m "feat: brief description"
+   ```
+
+3. **Test Locally**:
+
+   - Run `pytest` to ensure no regressions.
+   - Verify with examples from submodule READMEs.
+   - Check cross-platform (e.g., via GitHub Actions or local VMs).
+
+4. **Push and PR**:
+
+   ```bash
+   git push origin your-branch-name
+   ```
+   - Open a Pull Request (PR) to `main`.
+   - Reference related issues (e.g., "Fixes #123").
+   - Include changelog entry if breaking (in `CHANGELOG.md`).
+
+5. **Review and Merge**:
+
+   - Expect feedback; iterate as needed.
+   - Once approved, merge via squash/rebase (maintain clean history).
+   - Delete branch post-merge.
+
+## Pull Request Guidelines
+
+- **Title**: Clear and concise (e.g., "fix: resolve path resolution on Windows").
+- **Description**: 
+  - What/Why: Problem solved and motivation.
+  - How: Key changes.
+  - Tests: New/updated tests.
+  - Docs: Updated READMEs/examples.
+- **Scope**: Small, focused PRs (<300 lines preferred).
+- **CI Checks**: Must pass (linting, tests); re-run if needed.
+
+## Releasing
+
+Releases are managed by maintainers:
+
+- Bump version in `pyproject.toml`/`setup.py`.
+- Tag: `git tag vX.Y.Z`.
+- Push: `git push --tags`.
+- Upload to PyPI: `twine upload dist/*`.
+
+## Questions?
+
+- **Issues/PRs**: Use GitHub for tracking.
+- **Discussions**: [Start one](https://github.com/hbisneto/FileSystemPro/discussions/new) for ideas.
+- **Direct**: Email [[email protected]](mailto:[email protected]) or DM @BisnetoDev on X.
+
+Thanks for contributing—we're excited to collaborate! 🚀

ENFORCEMENT.md

@@ -0,0 +1,61 @@
+# Enforcement Guidelines for FileSystemPro
+
+This document outlines the process for handling reports of Code of Conduct violations in the FileSystemPro community. Our goal is to create a safe, inclusive environment where all participants feel welcome. Enforcement is carried out by the project maintainers, and we commit to handling all reports promptly, fairly, and transparently.
+
+## Reporting a Violation
+
+If you experience or witness behavior that violates the [Code of Conduct](CODE_OF_CONDUCT.md), please report it immediately. Reports should be sent to the project maintainers via:
+
+- **Email**: [[email protected]](mailto:[email protected])
+- **GitHub Issue**: Open a private issue marked as "Security" or "Confidential" (if sensitive).
+- **Direct Message**: DM @BisnetoDev on X (formerly Twitter) for urgent matters.
+
+Your report should include:
+- The nature of the incident (what happened, when, where—e.g., GitHub issue, PR, discussion).
+- Involved parties (usernames/emails, without sharing private info).
+- Any supporting evidence (screenshots, links—redact sensitive data).
+- Impact on you or the community.
+
+We will acknowledge your report within 48 hours and keep you updated on progress.
+
+## Confidentiality
+
+All reports are handled confidentially. We will not disclose your identity without explicit permission. Reports are shared only with other maintainers as needed for investigation. If the report involves a minor, we may involve appropriate authorities.
+
+## Investigation Process
+
+1. **Acknowledgment**: Confirm receipt and assure confidentiality.
+2. **Assessment**: Review the report against the Code of Conduct. If unclear, seek clarification.
+3. **Gathering Facts**: Collect additional context from involved parties (anonymously where possible). We may temporarily suspend actions (e.g., close issues) during review.
+4. **Decision**: Determine if a violation occurred and appropriate response (see below).
+5. **Resolution**: Implement actions and notify reporter/outcome (without violating privacy).
+6. **Follow-Up**: Check in with reporter post-resolution; update guidelines if patterns emerge.
+
+Investigations aim to conclude within 7 days, but complex cases may take longer. Maintainers prioritize empathy and proportionality.
+
+## Possible Responses
+
+Responses are tailored to severity and context, focusing on harm reduction and education:
+
+- **Warnings**: Private note to the individual, clarifying the issue and expected behavior.
+- **Temporary Restrictions**: Limit participation (e.g., comment muting, PR blocking) for 1-4 weeks.
+- **Permanent Bans**: Full exclusion from community spaces (e.g., repo access revoked).
+- **Escalation**: For severe cases (e.g., threats), involve law enforcement or GitHub support.
+
+No retaliation against reporters—any such behavior is a separate violation.
+
+## Appeals
+
+If you believe an enforcement action was unfair, appeal within 7 days via the same channels. Provide new evidence or context. Appeals are reviewed by at least two maintainers; decisions are final.
+
+## Maintainers' Responsibilities
+
+- **Training**: All maintainers review this document annually.
+- **Logging**: Track reports/actions internally (anonymized) for transparency.
+- **Updates**: Revise guidelines based on community feedback; announce changes.
+
+If you're a maintainer and need support, contact [[email protected]](mailto:[email protected]).
+
+## Attribution
+
+Adapted from the [Contributor Covenant Enforcement Guidelines](https://www.contributor-covenant.org/enforcement.html) and [Open Source Guide](https://opensource.guide/code-of-conduct/). Customizations for FileSystemPro include contact details and simplified processes.