Skip to content

Commit

Permalink
Merge pull request #123 from 444B/test/migrate-from-pipenv-to-uv
Browse files Browse the repository at this point in the history 
Test/migrate from pipenv to uv, python 3.12 and OIDC release methods
  • Loading branch information
@444B
444B authored Dec 26, 2024
2 parents 4ed7c36 + 53125fc commit 8d19359
Show file tree
Hide file tree
Showing 17 changed files with 1,910 additions and 2,203 deletions.
133 changes: 27 additions & 106 deletions .github/CONTRIBUTING.md
View file
Original file line number Diff line number Diff line change
@@ -1,128 +1,49 @@
# Contributing to Streamlit-Analytics2

# Contributing to Streamlit-Analytics

We love your input! We want to make contributing to this project as easy and transparent as possible, whether it's:

- Reporting a bug
- Discussing the current state of the code
- Submitting a fix
- Proposing new features
- Becoming a maintainer

## We Develop with GitHub

We use GitHub to host code, to track issues and feature requests, as well as accept pull requests.

## We Use GitHub Flow

All code changes happen through pull requests, so we suggest you familiarize yourself with [GitHub Flow](https://guides.github.com/introduction/flow/). Pull requests are the best way to propose changes to the codebase. We actively welcome your pull requests:

1. Fork the repo and create your branch from `main`. **Make sure to start your branch with the word "test/"**
2. Make sure your code lints by running tests on the code (described below)
3. Issue that pull request!

## Any contributions you make will be under the same license as the project

In short, when you submit code changes, your submissions are understood to be under the same [license](LICENSE.md) that covers the project. Feel free to contact the maintainers if that's a concern.

## Report bugs using Github's [issues](https://github.com/444B/streamlit-analytics2/issues/new/choose)

We use GitHub issues to track public bugs. Report a bug by [opening a new issue](https://github.com/444B/streamlit-analytics2/issues/new/choose); it's that easy!

**Great Bug Reports** tend to have:

- A quick summary and/or background
- Steps to reproduce
- Be specific!
- Give sample code if you can.
- What you expected would happen
- What actually happens
- Notes (possibly including why you think this might be happening, or stuff you tried that didn't work)

## Use a Consistent Coding Style

- We follow the [PEP 8](https://www.python.org/dev/peps/pep-0008/) style guide for Python code.
<!-- - Ensure your code passes the run_checks.sh (described below)
``` -->

## License

By contributing, you agree that your contributions will be licensed under its [License](LICENSE.md).

## Setting Up Your Development Environment

### 1. Clone the Repository
Navigate to the directory where you want to clone the repo and run:
## Getting Started
1. Fork and clone:
```sh
git clone https://github.com/444B/streamlit-analytics2.git
cd streamlit-analytics2
```

### 2. Create a New Branch
Create a new branch for your work:
```sh
git checkout -b name_of_your_new_branch
```
> **IMPORTANT**: Start the name of your branch with "test/". Pushing on this branch will trigger a release to [TestPyPI](https://test.pypi.org/project/streamlit-analytics2/) where we can further verify that the code works as expected.
### 3. Install Python and pipenv
Ensure you have Python 3.10.x installed, then install pipenv:
```sh
pip install --user pipenv
```

### 4. Create a Pipenv Environment
Set up your pipenv environment with Python at least python 3.10.
A higher version should be fine unless you are using cutting edge python expressions.
2. Create branch:
```sh
pipenv --python 3.10
git checkout -b test/your-feature-name
```

### 5. Install Dependencies
Install all necessary project dependencies. If you are writing/editing code, it is **highly** reccomended that to get the dev packages. You will need them if you intend on contributing code.
## Development Environment Setup
1. Install Python 3.12.x
2. Install and setup uv:
```sh
pipenv install --dev
pip install uv
uv venv
source .venv/bin/activate # On Windows: .venv\Scripts\activate
```

### 6. Activate the Virtual Environment
Activate your pipenv environment:
3. Install dependencies:
```sh
pipenv shell
pipenv update
uv pip install -e ".[dev]"
```

### 7. Write code, test new features!
Please note that the ```examples/minimap.py``` file is set to detect your file path and use the local code for ```streamlit_analytics2``` instead of a pip installed version. Just change the code in ```src/streamlit/analytics2/...py``` and it should be used in the example files.
>[!NOTE]Sometimes you might need to CTRL+C and restart streamlit. I havent yet figured out why save+rerun isnt working as expected.
### 8. Run a Minimal Example
Start with running a minimal Streamlit app to ensure everything is set up correctly:
4. Verify setup:
```sh
streamlit run examples/minimal.py
```

### 9. Before submitting
- Our code goes through robust checks to ensure safety and high quality. Our [workflows](https://github.com/444B/streamlit-analytics2/actions) are set up to detect issues in code and will fail a deployment if any issues are detected.
- To prevent lost time when reviewing the PR, please run the local test bash file to ensure that code in compliant.
## Quality Checks
```sh
cd tests/
chmod +x /run_checks.sh
chmod +x run_checks.sh
./run_check.sh
```

This will perform formatting and checks with the following packages:
- black (code formatting)
- isort (sorting imports)
- flake8 (Linting)
- mypy (Static type checking)
- bandit (Security scanning)
- pytest (test coverage)
```

## Additional Tips
## Pull Request Process
1. Push changes:
```sh
git add .
git commit -m "Your commit message"
git push origin test/your-feature-name
```
2. Open PR on GitHub

- **Troubleshooting**: If you encounter any issues, please check common pipenv errors and their solutions.
- **Making Contributions**: After testing your changes, commit them to your branch, push to your fork, and open a pull request against the main repository.
- **Environment Variables**: If the project requires specific environment variables, set them up according to the project documentation.
- **Testing and Linting**: Before submitting your pull request, ensure you run any tests and lint your code according to the project's guidelines.
For issues: [GitHub issue tracker](https://github.com/444B/streamlit-analytics2/issues/new/choose)

Thank you for contributing to streamlit-analytics2!
By contributing, you agree to the project's [license](LICENSE.md).
49 changes: 25 additions & 24 deletions .github/PULL_REQUEST_TEMPLATE.md
View file
Original file line number Diff line number Diff line change
@@ -1,34 +1,35 @@
# Pull Request Template
## Description

## TL;DR
Provide a brief summary of the changes made.
-
Briefly describe the changes made in this pull request.

## Problem Solved
1. Describe the problem your changes address.
2. Please mention the issue number if relevant
-
-
## Related Issue(s)

## Screenshots
If applicable, add screenshots to help explain your solution. For adding images, use:
-
- Closes #[issue number]

## Changes Made(Optional)
List the main changes in bullet points.
## Changes Made

- [ ] Change 1...
- [ ] Change 2...
- [ ] ...
- [ ] Change 1
- [ ] Change 2
- [ ] Change 3

## Manual Testing
- [ ] You have manually tested all changes to ensure they work as intended. Replace the [ ] with a [X] if True.
## Testing

- [ ] I have manually tested these changes and confirm they work as intended.

**How was this tested?**
Describe the tests that you ran to verify your changes.
-
**Testing Details:**
Describe how you tested the changes.

## Screenshots (if applicable)

Add any relevant screenshots here.

## Checklist

- [ ] I have read the [CONTRIBUTING](CONTRIBUTING.md) guide.
- [ ] I have commented my code, particularly in hard-to-understand areas.
- [ ] I have made corresponding changes to the documentation (README.md, CONTRIBUTING.md, etc.).
- [ ] My changes generate no new warnings or errors.

## Additional Notes
Include any additional information that might be relevant for reviewers.
-

Add any other notes or context about the pull request here.
82 changes: 26 additions & 56 deletions .github/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,78 +11,48 @@

**Enhanced tracking & visualization for your Streamlit apps.**

`streamlit-analytics2` is a fork and extension of the original [streamlit-analytics](https://github.com/jrieke/streamlit-analytics), aimed at improving and securing the analytics functionality within Streamlit applications. With minimal setup, track user interactions and visualize analytics directly in your browser, akin to Google Analytics but tailored for Streamlit.

This fork was initiated due to the inability to collaborate directly on the upstream project, which currently has several unresolved security issues and bugs. Our intention is to maintain a positive relationship with the original project and its creator, focusing on enhancing the tool's reliability and security for the community.
Streamlit Analytics2 is a maintained, powerful tool for tracking user interactions and gathering insights from your Streamlit applications. With just a few lines of code, you can start monitoring user behavior and making data-driven decisions to improve your app.

> [!Note]
> This fork is confirmed to fix the deprecation ```st.experimental_get_query_params``` alerts. [Context](https://docs.streamlit.io/library/api-reference/utilities/st.experimental_get_query_params)
> It also resolved 25 security issues that exist in the upstream (2 Critical, 11 High, 10 Moderate, 2 Low)
<sup>This project is in active development. We welcome contributions and address security concerns on a best-effort basis, with details available in our [CONTRIBUTING.md](CONTRIBUTING.md) and [SECURITY.md](SECURITY.md) respectively.</sup>


## Installation

```bash
pip install streamlit-analytics2
```

## Migration from upstream streamlit-analytics

Only two single characters need to be changed and this has been tested and verified to work.
1. Change your requirements.txt or other dependency file to use 'streamlit-analytics**2**'. Just add a '2'
2. Change your code import to use 'streamlit_analytics**2** as streamlit_analytics'. Also, just add a '2'. Seen below.

> [!IMPORTANT]
> This project aims to be backwards compatible with the upstream and migration literally just means adding the number 2 and getting the new package.
> The above steps should be sufficient but if you need more steps, check out our [Migration Guide](https://github.com/444B/streamlit-analytics2/wiki/0.--Migration-Guide-from-streamlit%E2%80%90analytics-to-streamlit%E2%80%90analytics2).
## Getting Started

## How to Use
1. Install the package:
```
pip install streamlit-analytics2
```

Simple integration with any Streamlit app:
2. Import and initialize the tracker in your Streamlit script:
```python
import streamlit as st
import streamlit_analytics2 as streamlit_analytics

```python
import streamlit as st
import streamlit_analytics2 as streamlit_analytics
with streamlit_analytics.track():
st.write("Hello, World!")
st.button("Click me")
```

with streamlit_analytics.track():
st.write("Hello, World!")
st.button("Click me")
```
3. Run your Streamlit app and append `?analytics=on` to the URL to view the analytics dashboard.

All interactions are now tracked, supporting all standard Streamlit widgets.

Another way to get the tracking is to call the streamlit_analytics.track() on your main() function:
```python
import streamlit as st
import streamlit_analytics2 as streamlit_analytics

with streamlit_analytics.track():
main()

def main():
st.write("Hello, World!")
st.button("Click me")
```
Using streamlit_analytics.track() is the recommended method and will become the primary way to initiate streamlit-analytics2 after the [upcoming v.1.0.0](https://github.com/444B/streamlit-analytics2/issues/53) release.
## Contributing

## Moving Forward
We're actively seeking additional maintainers to help improve Streamlit Analytics2. If you're interested in contributing, please check out our [Contributing Guidelines](.github/CONTRIBUTING.md) to get started. We welcome pull requests, bug reports, feature requests, and any other feedback.

- **TODOs and Feature Requests**: We've transitioned our roadmap and feature requests to [GitHub Issues](https://github.com/your-repo/streamlit-analytics2/issues). Feel free to contribute ideas or report bugs!
- **Advanced Configuration**: Detailed guidance on advanced setup (including password protection and database integration) options are available in our [Project Wiki](https://github.com/444B/streamlit-analytics2/wiki).
- **Improved Performance**: We are focused on providing a use of streamlit-analytics2 that doesn't impact the performance of your app.
All suggestions and inputs are welcome on our [forum](https://github.com/444B/streamlit-analytics2/discussions)

## Contributing
## Upcoming Features

Your contributions are welcome! Please refer to our [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on how to make a difference.
The step by step guide will show you how to set up a dev environment, testing standards and how to make a PR.
We're currently working on a major breaking release that will introduce exciting new features and enhancements:

## Security
- Multi-page tracking: Monitor user interactions across multiple pages of your Streamlit app.
- Improved metrics accuracy: Get more precise and reliable usage metrics.
- Flexible data formats: Choose between CSV or JSON for storing and exporting analytics data.
- Customization screen: Easily configure and customize the analytics settings through a user-friendly interface.

We prioritize the security of our users' data. For reporting security vulnerabilities or for more information, please review our [SECURITY.md](SECURITY.md).
Stay tuned for more updates and join our [community](https://github.com/444B/streamlit-analytics2/discussions) to be part of shaping the future of Streamlit Analytics2!

## Acknowledgments
## License

A special thanks to [jrieke](https://github.com/jrieke) and all contributors to the original `streamlit-analytics` project. Your work has inspired continued innovation and community collaboration.
This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for more information.
41 changes: 34 additions & 7 deletions .github/dependabot.yml
View file
Original file line number Diff line number Diff line change
@@ -1,11 +1,38 @@
# To get started with Dependabot version updates, you'll need to specify which
# package ecosystems to update and where the package manifests are located.
# Please see the documentation for all configuration options:
# https://docs.github.com/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file

version: 2
updates:
- package-ecosystem: "pip" # See documentation for possible values
directory: "/" # Location of package manifests
- package-ecosystem: "pip"
directory: "/"
schedule:
interval: "weekly"
# Add these recommended settings
allow:
# Only handle production dependencies by default
- dependency-type: "production"
commit-message:
prefix: "deps"
include: "scope"
# Group updates together
groups:
dev-dependencies:
patterns:
- "black"
- "isort"
- "flake8"
- "mypy"
- "bandit"
- "pytest*"
production-dependencies:
patterns:
- "streamlit"
- "pandas"
- "altair"
- "google-cloud-firestore"
# Specify target branch
target-branch: "main"
# Set reviewers for the PRs
reviewers:
- "444B"
# Labels for PRs
labels:
- "dependencies"
- "automated"
Loading

0 comments on commit 8d19359

Please sign in to comment.