spherapy 0.2.0__tar.gz

spherapy-0.2.0/.github/ISSUE_TEMPLATE/bug_report.yaml

@@ -0,0 +1,74 @@
+name: Bug Report
+description: Create a new bug report.
+title: '[Bug]: <title>'
+labels: [type:bug]
+body:
+
+  - type: checkboxes
+    attributes:
+      label: Is there an existing issue for this?
+      description: 'Please [search :mag: the issues](https://github.com/rzmearns/spherapy/issues) (open & closed) to check if this bug has already been reported.'
+      options:
+      - label: I have searched the existing issues
+        required: true
+  
+  - type: input
+    attributes:
+      label: Spherapy Version
+      description: What spherapy version are you using?
+      placeholder: Output of `spherapy.__version__`
+    validations:
+      required: true
+
+  - type: checkboxes
+    attributes:
+      label: Is this issue reproducible using the latest spherapy version?
+      description: |
+        You can check the latest spherapy version number at [pypi-spherapy](https://pypi.org/project/spherapy/). If you are not up to date, please try to reproduce your issue after updating.
+      options:
+      - label: I confirm the issue is still reproducible with the latest version
+
+  - type: textarea
+    attributes:
+      label: Current Behaviour
+      description: Describe the problem you are experiencing. Screenshots are welcome. Please enclose copied code in ```.
+    validations:
+      required: true
+
+  - type: textarea
+    attributes:
+      label: Expected Behaviour
+      description: Describe what you expect to happen instead.
+    validations:
+      required: true
+
+  - type: textarea
+    attributes:
+      label: Environment Details
+      description: |
+        Please provide additional information about your environment; python version, etc.
+
+        :warning: _Remember to redact or remove any sensitive information!_
+      value: |
+          - Python version
+          - Are you running python in a virtual environment
+          - Are you using the default spherapy configuration or using a SPHERAPY_CONFIG_DIR:
+          - Are you using spacetrack credentials, or faling back to celestrak
+          - Last spherapy version(s) which did _not_ exhibit the problem:
+
+  - type: textarea
+    attributes:
+      label: Minimal Reproducible Example
+      description: |
+        Please provide [the smallest, complete code snippet](https://stackoverflow.com/help/minimal-reproducible-example) that spherapy's maintainers can run to reproduce the issue. An easy way to get started is to copy the examples in [README](https://github.com/rzmearns/spherapy/blob/main/README.md) and modify it accordingly. Failing this, any sort of reproduction steps are better than nothing!
+    validations:
+      required: true
+
+  - type: textarea
+    attributes:
+      label: Further Information
+      description: If needed, please provide additional information about your issue (attachments, links, references, etc.).
+
+  - type: markdown
+    attributes:
+      value: ':stop_sign: _Make sure you are reporting a problem with spherapy. For general questions, please ask a [question](https://github.com/rzmearns/spherapy/issues)_'

spherapy-0.2.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,17 @@
+blank_issues_enabled: false
+issue_templates:
+  - name: "Question"
+    description: "Ask a questino"
+    title: "[Question]: "
+    labels: ["type:support"]
+    body: "./ISSUE_TEMPLATE/question.md"
+  - name: "Bug Report"
+    description: "Report a bug with spherapy"
+    title: "[Bug]: "
+    labels: ["type:bug"]
+    body: "./ISSUE_TEMPLATE/bug_report.md"
+  - name: "Feature Request"
+    description: "Request a new spherapy feature"
+    title: "[Feature]: "
+    labels: ["type:enhancement"]
+    body: "./ISSUE_TEMPLATE/feature_request.md"

spherapy-0.2.0/.github/ISSUE_TEMPLATE/feature_request.yaml

@@ -0,0 +1,33 @@
+name: Feature/Documentation Request
+description: Suggest an idea for this project.
+title: "[Feature]: <title>"
+labels: [type:enhancement]
+body:
+
+  - type: textarea
+    attributes:
+      label: Is your feature/documentation request related to a problem?
+      description: A clear and concise description of what the problem is. Eg. I'm always frustrated when [...].
+    validations:
+      required: true
+
+  - type: textarea
+    attributes:
+      label: Describe the solution you'd like.
+      description: A clear and concise description of what you want to happen.
+    validations:
+      required: true
+
+  - type: textarea
+    attributes:
+      label: Describe alternatives you've considered.
+      description: A clear and concise description of any alternative solutions or features you've considered.
+    validations:
+      required: false
+
+  - type: textarea
+    attributes:
+      label: Additional context
+      description: Add any other context or screenshots about the feature request here.
+    validations:
+      required: false

spherapy-0.2.0/.github/ISSUE_TEMPLATE/question.yaml

@@ -0,0 +1,24 @@
+name: Question
+description: Create a new question.
+title: '[Question]: <title>'
+labels: [type:support]
+body:
+
+  - type: checkboxes
+    attributes:
+      label: Is there an existing question for this?
+      description: 'Please [search :mag: the issues](https://github.com/rzmearns/spherapy/issues) to check if this question has already been asked.'
+      options:
+      - label: I have searched the existing issues
+        required: true
+
+  - type: textarea
+    attributes:
+      label: Question
+      description: What is your question?
+    validations:
+      required: true
+
+  - type: markdown
+    attributes:
+      value: ':stop_sign: _Make sure you are asking a question about spherapy. For reporting bugs, or requesting features, please submit an [issue](https://github.com/rzmearns/spherapy/issues)_'

spherapy-0.2.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,27 @@
+## Proposed changes
+
+Describe the big picture of your changes here to communicate to the maintainers why we should accept this pull request. If it fixes a bug or resolves a feature request, be sure to link to that issue.
+
+## Types of changes
+
+What types of changes does your code introduce to spherapy?
+_Put an `x` in the boxes that apply_
+
+- [ ] Bugfix (non-breaking change which fixes an issue)
+- [ ] New feature (non-breaking change which adds functionality)
+- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
+- [ ] Documentation Update (modifying function documentation, or providing examples)
+- [ ] Infrastructure Update (modifying tests, CI pipeline, etc.)
+
+## Checklist
+
+_Put an `x` in the boxes that apply. You can also fill these out after creating the PR. If you're unsure about any of them, don't hesitate to ask. We're here to help! This is simply a reminder of what we are going to look for before merging your code._
+
+- [ ] I have read the [Contributing Guide](https://github.com/rzmearns/spherapy/blob/main/CONTRIBUTING.md)
+- [ ] Lint, typing, and unit tests pass locally with my changes
+- [ ] I have added tests that prove my fix is effective or that my feature works
+- [ ] I have added the necessary documentation
+
+## Further comments
+
+If this is a relatively large or complex change, kick off the discussion by explaining why you chose the solution you did and what alternatives you considered, etc...

spherapy-0.2.0/.github/workflows/pr.yml

@@ -0,0 +1,74 @@
+name: PR pipeline
+
+on: 
+  pull_request:
+    branches:
+      - 'main'
+    paths:
+      - '**.py'
+      - 'pyproject.toml'
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - run: echo "Running lint from merge of ${{ github.event.pull_request.head.ref }} on commit ${{ github.event.pull_request.head.sha }}"
+      - id: lint-checkout
+        name: Checkout
+        uses: actions/checkout@v5
+      - id: lint-install-python
+        name: Set up Python 3.12
+        uses: actions/setup-python@v6
+        with:
+          python-version: 3.12
+          cache: pip
+      - id: lint-install-dependencies
+        name: Install dependencies
+        run: pip install --editable .[dev]
+      - id: lint-run
+        run: ruff check
+
+  type:
+    runs-on: ubuntu-latest
+    steps:
+      - run: echo "Running static type analysis from merge of ${{ github.event.pull_request.head.ref }} on commit ${{ github.event.pull_request.head.sha }}"
+      - id: type-checkout
+        name: Checkout for Typing
+        uses: actions/checkout@v5
+      - id: type-install-python
+        name: Set up Python 3.12
+        uses: actions/setup-python@v6
+        with:
+          python-version: 3.12
+          cache: pip
+      - id: type-install-dependencies
+        name: Install dependencies for Typing
+        run: pip install --editable .[dev]
+      - id: type-run
+        run: mypy spherapy --disable-error-code=import-untyped
+
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+    steps:
+      - run: echo "Running tests from merge of ${{ github.event.pull_request.head.ref }} on commit ${{ github.event.pull_request.head.sha }}"
+      - id: checkout
+        name: Checkout
+        uses: actions/checkout@v5
+      - id: install-python
+        name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+      - id: install-dependencies
+        name: Install dependencies
+        run: pip install --editable .[dev]
+      - id: pytest-run
+        name: Running Pytest
+        run: |
+          export SPHERAPY_CONFIG_DIR="."
+          python -m pytest
+

spherapy-0.2.0/.github/workflows/release.yml

@@ -0,0 +1,31 @@
+name: release
+
+on: 
+  release:
+    types: [published]
+
+jobs:
+  build-release:
+    runs-on: ubuntu-latest
+    steps:
+      - id: checkout
+        name: Checkout
+        uses: actions/checkout@v5
+        with:
+          fetch-depth: 0
+      - id: install-python
+        name: Set up Python 3.12
+        uses: actions/setup-python@v6
+        with:
+          python-version: 3.12
+          cache: pip
+      - id: install-dependencies
+        name: Install dependencies for Build
+        run: pip install build twine
+      - id: build-run
+        run: python -m build
+      - id: publish-run
+        env:
+          TWINE_USERNAME: __token__
+          TWINE_PASSWORD: ${{ secrets.PYPI_TOKEN }}
+        run:  python -m twine upload --verbose dist/*

spherapy-0.2.0/.gitignore

@@ -0,0 +1,93 @@
+# Specific Project Directories #
+################################
+data/spacetrack
+data/TLEs
+
+# Compiled source #
+###################
+*.pyc
+*.vscode
+build
+
+# Environment #
+############
+env/
+venv/
+.venv/
+spherapy-env/
+
+# Packages #
+############
+# it's better to unpack these files and commit the raw source
+# git has its own built in compression methods
+*.7z
+*.dmg
+*.gz
+*.iso
+*.jar
+*.rar
+*.tar
+*.zip
+*.egg-info
+
+# Logs and databases #
+######################
+*.log
+*.out
+*.sql
+*.sqlite
+*.json
+*.console
+*.bsp
+
+# Caches #
+######################
+*__pycache__
+*.pytest_cache
+*.cache
+*.tags*
+*.ruff_cache
+*.pytest_cache
+*.mypy_cache
+
+# OS generated files #
+######################
+.DS_Store
+.DS_Store?
+._*
+.Spotlight-V100
+.Trashes
+ehthumbs.db
+Thumbs.db
+
+# Data files #
+######################
+*.dat
+*.mat
+*.npy
+*.pickle
+*.dbf
+*.prj
+*.shp
+*.shx
+*.cpg
+*.html
+*.txt
+*.tle
+*.temptle
+
+# Backup files #
+######################
+*.m~
+*.xls#
+*.xlsx#
+*.doc#
+*.docx#
+*.ppt#
+*.csv#
+
+
+*.csv
+*.icloud
+*.nc
+*.nc4

spherapy-0.2.0/.pre-commit-config.yaml

@@ -0,0 +1,10 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.12.3  # Ruff version.
+    hooks:
+      - id: ruff-check # Run the linter.
+        args: [--config=pyproject.toml]
+  - repo: https://github.com/gitleaks/gitleaks
+    rev: v8.24.2
+    hooks:
+      - id: gitleaks

spherapy-0.2.0/CHANGELOG.md

@@ -0,0 +1,12 @@
+The change log should include
+- theme of the upversion
+- changes in API
+- changes in model behaviour
+
+# v0.2.0
+- initial release to pypi
+- timespan object
+- orbit object
+- orbit object creation from: TLE, propagated orbital parameters, analytical orbital parameters, list of positions
+- TLE updater, pulls requested TLEs from spacetrack, stores all TLEs for that satellite in a saved file
+- TLE updater falls back to celestrak if no credentials provided

spherapy-0.2.0/CONTRIBUTING.md

@@ -0,0 +1,125 @@
+# Contribution Guide
+
+## How to Contribute
+Almost all communication with the spherapy maintainers should be done through the main spherapy Github repository: https://github.com/rzmearns/spherapy
+
+- Bug reports and feature requests can be submitted through the [Issues](https://github.com/rzmearns/spherapy/issues) page on the repository. It is critical that sufficient information is provided in the bug report to recreate the problem. Please provide:
+  - The spherapy version
+  - The python version
+  - A description of the behaviour.
+  - The TLE files which resulted in the bug
+  - The timespan settings
+
+- Any changes to actual code, including documentation, should be submitted as a pull request on Github.
+  - Please make sure to submit pull requests using a new branch following the [Branch Naming Convention](#branch-naming-convention). Don’t be afraid to create a pull request as soon as the branch is created. It can be always be updated later. Creating them early gives maintainers a chance to provide an early review of your code if that’s something you’re looking for. See below for more information on writing documentation and checking your changes.
+  - Make sure you understand the overall architecture of spherapy before adding features.
+
+- No matter how you contribute, spherapy maintainers will try their best to read, research, and respond to your query as soon as possible. For code changes, automated checks and tests will run on Github to provide an initial “review” of your changes.
+
+## Submitting Bugs
+Please submit problems or bugs as issues in github, they will be tagged by a maintainer as a `bug`
+
+https://github.com/rzmearns/spherapy/issues
+
+## Submitting Feature Ideas
+Please submit feature ideas as an issue in Github, they will be tagged by a maintainer as an `enhancement`
+
+https://github.com/rzmearns/spherapy/issues
+
+## Asking Questions
+Please submit questions as an issue in Github, they will be tagged by a maintainer as `support`
+
+https://github.com/rzmearns/spherapy/issues
+
+## Adding Features
+If you have a contribution to make to spherapy, please clone the repo, and submit a pull request.  
+In order to be considered for merging, the branch must pass the [Linting](#linting), [Testing](#testing) and [Static Typing](#typing) stages of the CI pipeline.  
+For any branch you make, please follow the following branch naming conventions:
+
+### Branch Naming Convention
+- If a branch is adding a feature to spherapy: `feature/{descriptive_name}`
+  - the feature must be supported by unit tests included in the branch
+  - will results in a minor upversion
+- If a branch is fixing a spherapy bug: `bugfix/{descriptive_name}` or `bugfix/{ISSUE#}`
+  - the bugfix must be supported by regrestion tests included in the branch
+  - will result in a patch upversion
+- If a branch is modifying or fixing a bug in the infrastructure (CI, etc.): `infrastucture/{descriptive_name}` or `infrastructure/{ISSUE#}`
+- If a branch is updating the documentation: `docs/{descriptive_name}`
+- The maintainers may use `hotfix/{descriptive_name}` or `hotfix/{ISSUE#}` if an urgent fix is required to the main branch
+  - will result in a patch upversion
+
+
+## Development Environment
+It is recommended that you setup a virtual environment running python 3.12 (spherapy is compatible with 3.10->3.12), and install the packages required within that virtual environment.
+
+### Virtual Environment
+```
+pip install virtualenv
+virtualenv -p=`which python3.12` .venv312
+source .venv312/bin/activate
+```
+
+### Clone and install spherapy
+```
+git clone git@github.com:rzmearns/spherapy.git
+pip install --editable .[dev]
+```
+
+### Linting
+Linting is acheived using Ruff. The necessary packages will be installed as part of the \[dev\] depenedencies.  
+Spherapy has an extensive list of linter warnings enabled by default, the full list can be found in the pyproject.toml under [tool.ruff.lint], while the explanation to each class of error, and specific errors can be found on Ruff's website, [Rules](https://docs.astral.sh/ruff/rules/)
+
+If there is a good reason, individual linting errors can be excluded, but not entire error classes.
+
+For coding style guidelines, see [Coding Style](#coding-style)
+
+linting can be run locally using
+```
+ruff check
+```
+Tedious changes, for example sorting the import blocks, can be handled automatically by Ruff:
+```
+ruff check --fix
+```
+Linting will be automatically run whenever a commit is made to a pull request.
+
+### Testing
+Testing is achieved with pytest and pytest-check. The necessary packages will be installed as part of the \[dev\] depenedencies.  
+Tests should be located in the `tests/` dir, following a similar structure to the package structure.  
+If you add functionality to spherapy, there should be dedicated unit tests for each feature. If you contribute by fixing a bug, tests should be added to ensure that the bug does not get reintroduced in future merges. These regression tests should have a comment note detailing what they are protecting against.  
+
+spherapy often uses pytest-check to run all tests in a function in parallel, so that any one failure does not stop other tests in that function from running.  
+
+tests can be run locally using 
+```
+pytest
+```
+
+Tests will be automatically run whenever a commit is made to a pull request. (The tests will run under python3.10, python3.11 and python3.12)
+
+### Typing
+spherapy employs static type analysis using mypy (hopefully this will be changed to ty in the future). The necessary packages will be installed as part of the \[dev\] depenedencies.
+
+Static typing can be run locally using
+```
+mypy spherapy --disable-error-code=import-untyped
+```
+The `--disable-error-code=import-untyped` flag is necessary to avoid errors with untyped libraries like astropy.
+
+Static typing will be automatically run whenever a commit is made to a pull request.
+
+### pre-commit hooks
+Although not necessary, it is recommended to use [pre-commit](https://pre-commit.com/). The necessary packages will be installed as part of the \[dev\] depenedencies.  
+This runs configured checks on the codebase prior to every commit. The configured checks can be seen in [.pre-commit-config.yaml](https://github.com/rzmearns/spherapy/blob/main/.pre-commit-config.yaml)  
+The configured checks for spherapy are:
+- `ruff check`
+- `gitleaks`
+
+To configure pre-commit, after `pip install .[dev]`, run `pre-commit install`
+
+## Coding Style
+In general, spherapy follows a modified PEP 8 style guidelines, that are enforced by the linter. The notable differences are:
+- all indentations are TABS (NOT SPACES.)
+- variables are snake_case (this_is_a_variable) (like PEP8)
+- functions are mixedCase (thisIsAFunction)
+  - if there is an acronym in the function name, it should be in UPPERCASE.

spherapy-0.2.0/LICENSE.md

@@ -0,0 +1,19 @@
+Copyright © 2025 Robert Mearns
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.