HIM-public/elytra_client
HIM-public/elytra_client
5
0
Fork 0
Code Issues Pull requests Projects Releases 1 Packages 1 Wiki Activity Actions

Add Forgejo PyPI support and update .gitignore for sensitive files

Browse source
This commit is contained in:
claudi 2026-02-20 09:55:42 +01:00
parent b8a7fb903e
commit 4fd9f13f36
7 changed files with 636 additions and 55 deletions
Download patch file Download diff file Expand all files Collapse all files

283
BUILD.md
View file

@ -151,68 +151,217 @@ Or with dev dependencies:
pip install -e ".[dev]"
```
## Uploading to PyPI
## Uploading to Forgejo PyPI
### Prerequisites
This project uses **Forgejo PyPI** for package distribution, not the public PyPI. Forgejo is a self-hosted Git service with integrated package registry support.
1. Create PyPI account at https://pypi.org/
2. Create PyPI token: https://pypi.org/manage/account/tokens/
3. Configure credentials
### Setup Forgejo PyPI
### Using twine
#### Step 1: Create .pypirc Configuration
Copy the example configuration:
```bash
# Install twine
pip install twine
# Upload to PyPI (after building)
twine upload dist/*
# Or to TestPyPI for testing first
twine upload -r testpypi dist/*
cp .pypirc.example .pypirc
```
### Authentication
**Option 1: Using .pypirc file**
Create `~/.pypirc`:
Edit `.pypirc` with your Forgejo details:
```ini
[distutils]
index-servers =
pypi
testpypi
forgejo
[pypi]
repository = https://upload.pypi.org/legacy/
[forgejo]
repository = https://your-forgejo-instance.com/api/packages/YOUR_USERNAME/pypi
username = __token__
password = pypi_your_token_here
[testpypi]
repository = https://test.pypi.org/legacy/
username = __token__
password = pypi_your_test_token_here
password = YOUR_ACCESS_TOKEN
```
**Option 2: Interactive prompt**
#### Step 2: Generate Forgejo Personal Access Token
twine will prompt for username and password when uploading.
1. Visit your Forgejo instance: `https://your-forgejo-instance.com`
2. Go to: **User Settings** → **Applications**
3. Click **Create New Token**
4. Name it: `PyPI Upload`
5. Grant scope: **write:packages**
6. Copy the generated token
7. Paste into `.pypirc` as `password`
### Upload to Test PyPI First
#### Step 3: Secure .pypirc
Before uploading to production, test with TestPyPI:
**IMPORTANT:** Add `.pypirc` to `.gitignore` to prevent committing credentials!
```bash
twine upload -r testpypi dist/*
echo ".pypirc" >> .gitignore
git add .gitignore
git commit -m "chore: add .pypirc to gitignore"
```
Then test installation:
### Uploading to Forgejo PyPI
**Requirement:** twine must be installed (see Prerequisites section above)
#### Option 1: Using PowerShell Script (Windows - Recommended)
```powershell
# Activate virtual environment first
.\.venv\Scripts\Activate.ps1
# Upload existing wheel
.\upload_wheel_to_forgejo_pypi.ps1
# Rebuild and upload
.\upload_wheel_to_forgejo_pypi.ps1 -Build
# Show help
.\upload_wheel_to_forgejo_pypi.ps1 -Help
```
#### Option 2: Using Batch Script (Windows)
```batch
upload_wheel_to_forgejo_pypi.bat
REM Rebuild and upload
upload_wheel_to_forgejo_pypi.bat --build
```
#### Option 3: Using Shell Script (Unix/Linux)
```bash
pip install -i https://test.pypi.org/simple/ elytra-pim-client==0.1.0
# Make script executable (first time only)
chmod +x upload_wheel_to_forgejo_pypi.sh
# Upload existing wheel
./upload_wheel_to_forgejo_pypi.sh
# Rebuild and upload
./upload_wheel_to_forgejo_pypi.sh --build
# Show help
./upload_wheel_to_forgejo_pypi.sh --help
```
#### Option 4: Using twine Directly
```bash
# Activate virtual environment
.venv\Scripts\activate # Windows
source .venv/bin/activate # macOS/Linux
# Upload wheel to Forgejo (twine is already in requirements.txt)
twine upload -r forgejo dist/*.whl
```
### What the Upload Scripts Do
1. **Load credentials** - Reads .pypirc configuration
2. **Setup environment** - Copies .pypirc to user home directory temporarily
3. **Activate venv** - Sets up Python virtual environment
4. **Build wheel** - Builds wheel if not present (or with --build flag)
5. **Upload** - Uploads wheel to Forgejo PyPI repository using twine
6. **Cleanup** - Removes temporary credentials from home directory
7. **Deactivate** - Deactivates virtual environment
### Accessing Your Package
After upload, your package is available in the Forgejo PyPI repository:
```bash
# Install from Forgejo PyPI
pip install --index-url https://your-forgejo-instance.com/api/packages/YOUR_USERNAME/pypi/simple/ elytra-pim-client
# Or add to requirements.txt
-i https://your-forgejo-instance.com/api/packages/YOUR_USERNAME/pypi/simple/
elytra-pim-client
```
### Troubleshooting Upload Issues
#### "Upload failed" Error
**Check:** Verify .pypirc configuration
```ini
[forgejo]
repository = https://correct-url.com/api/packages/USERNAME/pypi
username = __token__
password = VALID_TOKEN
```
**Verify:** Token has correct permissions
- Token must have `write:packages` scope
- Visit: `https://your-forgejo-instance.com/user/settings/applications`
**Network:** Ensure Forgejo instance is reachable
```bash
curl https://your-forgejo-instance.com/api/v1/user
```
#### ".pypirc not found" Error
Create it from template:
```bash
cp .pypirc.example .pypirc
# Then edit with your credentials
```
#### "twine: command not found" Error
**Solution:** twine is included in `requirements.txt` as a development dependency. Install all dependencies:
```bash
pip install -r requirements.txt
```
### Example Workflow
```bash
# 1. Setup Forgejo PyPI (first time only)
cp .pypirc.example .pypirc
# Edit .pypirc with your Forgejo repository URL and credentials
echo ".pypirc" >> .gitignore
git add .gitignore
git commit -m "chore: add .pypirc to gitignore"
# 2. Make code changes
git commit -am "feat: add new feature"
# 3. Update version in pyproject.toml
# version = "0.2.0"
# 4. Build and upload to Forgejo PyPI
.\upload_wheel_to_forgejo_pypi.ps1 # PowerShell
# or
./upload_wheel_to_forgejo_pypi.sh # Bash/Shell
# or
./upload_wheel_to_forgejo_pypi.bat # Batch
# 5. Tag and push release
git tag v0.2.0
git push origin v0.2.0
```
## Uploading to Public PyPI (Future)
To upload to public PyPI instead of Forgejo:
1. Install twine: `pip install twine`
2. Create account at https://pypi.org/
3. Generate token at https://pypi.org/manage/account/tokens/
4. Create `.pypirc`:
```ini
[distutils]
index-servers =
pypi
[pypi]
repository = https://upload.pypi.org/legacy/
username = __token__
password = pypi_your_token_here
```
5. Upload: `twine upload -r pypi dist/*.whl`
## Versioning
### Version Format
@ -325,53 +474,77 @@ python -m build --verbose
```
elytra_client/
├── build_wheel.py # Python build script (all platforms)
├── build_wheel.ps1 # PowerShell build script (Windows)
├── build_wheel.sh # Shell build script (Unix/Linux)
├── build_requirements.txt # Build dependencies
├── setup.py # Setup configuration (legacy compatibility)
├── pyproject.toml # Modern build configuration (PEP 517/518)
├── MANIFEST.in # (Optional) File inclusion rules
└── dist/ # Output directory for distributions
├── build_wheel.py # Python build script (all platforms)
├── build_wheel.ps1 # PowerShell build script (Windows)
├── build_wheel.sh # Shell build script (Unix/Linux)
├── upload_wheel_to_forgejo_pypi.bat # Batch upload script (Windows)
├── upload_wheel_to_forgejo_pypi.ps1 # PowerShell upload script (Windows)
├── upload_wheel_to_forgejo_pypi.sh # Shell upload script (Unix/Linux)
├── .pypirc.example # Forgejo PyPI configuration template
├── .pypirc # Forgejo PyPI credentials (in .gitignore!)
├── build_requirements.txt # Build dependencies
├── setup.py # Setup configuration (legacy compatibility)
├── pyproject.toml # Modern build configuration (PEP 517/518)
└── dist/ # Output directory for distributions
├── elytra_pim_client-0.1.0-py3-none-any.whl
└── elytra_pim_client-0.1.0.tar.gz
```
## Best Practices
1. **Always test before releasing**
1. **Setup Forgejo PyPI (first time only)**
```bash
twine upload -r testpypi dist/*
pip install -i https://test.pypi.org/simple/ elytra-pim-client==0.1.0
cp .pypirc.example .pypirc
# Edit .pypirc with your Forgejo credentials
echo ".pypirc" >> .gitignore
```
2. **Increment version for each release**
2. **Complete release workflow**
```bash
# Update version in pyproject.toml
# version = "0.2.0"
# Build and upload
.\upload_wheel_to_forgejo_pypi.ps1
# Tag and push
git tag v0.2.0
git push origin v0.2.0
```
3. **Increment version for each release**
- Patch: Bug fixes (0.1.1)
- Minor: New features (0.2.0)
- Major: Breaking changes (1.0.0)
3. **Clean before rebuilding**
4. **Clean before rebuilding**
```bash
python build_wheel.py # Automatically cleans
# Or manually
rm -rf dist/ build/ *.egg-info/
```
4. **Keep dependencies minimal**
5. **Keep dependencies minimal**
- Only required packages in `dependencies`
- Development tools in `[project.optional-dependencies]`
5. **Document changes**
- Update CHANGELOG.md (if present)
- Update version in pyproject.toml
- Create git tag for release
6. **Use .pypirc template**
- Never commit `.pypirc` with real credentials
- Always keep `.pypirc` in `.gitignore`
- Share `.pypirc.example` with template values
7. **Secure credential handling**
- Use Forgejo personal access tokens with limited scope
- Rotate tokens regularly
- Never share tokens or .pypirc files
## Resources
- [Forgejo Documentation](https://docs.forgejo.org/)
- [Forgejo PyPI Package Registry](https://docs.forgejo.org/en/latest/usage/packages/pypi/)
- [Python Packaging Guide](https://packaging.python.org/)
- [PEP 517 - Build System Interface](https://www.python.org/dev/peps/pep-0517/)
- [PEP 518 - pyproject.toml](https://www.python.org/dev/peps/pep-0518/)
- [PEP 440 - Version Identification](https://www.python.org/dev/peps/pep-0440/)
- [setuptools Documentation](https://setuptools.pypa.io/)
- [twine Documentation](https://twine.readthedocs.io/)
- [PyPI Help](https://pypi.org/help/)