starteller-cli 1.0.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (15) hide show
  1. starteller_cli-1.0.0/LICENSE +61 -0
  2. starteller_cli-1.0.0/PKG-INFO +160 -0
  3. starteller_cli-1.0.0/README.md +131 -0
  4. starteller_cli-1.0.0/pyproject.toml +54 -0
  5. starteller_cli-1.0.0/setup.cfg +4 -0
  6. starteller_cli-1.0.0/src/__init__.py +23 -0
  7. starteller_cli-1.0.0/src/catalog_manager.py +445 -0
  8. starteller_cli-1.0.0/src/starteller_cli.py +1377 -0
  9. starteller_cli-1.0.0/starteller_cli.egg-info/PKG-INFO +160 -0
  10. starteller_cli-1.0.0/starteller_cli.egg-info/SOURCES.txt +13 -0
  11. starteller_cli-1.0.0/starteller_cli.egg-info/dependency_links.txt +1 -0
  12. starteller_cli-1.0.0/starteller_cli.egg-info/entry_points.txt +2 -0
  13. starteller_cli-1.0.0/starteller_cli.egg-info/requires.txt +5 -0
  14. starteller_cli-1.0.0/starteller_cli.egg-info/top_level.txt +1 -0
  15. starteller_cli-1.0.0/tests/test_starteller_cli.py +537 -0
starteller_cli-1.0.0/LICENSE ADDED
@@ -0,0 +1,61 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2025 StarTeller-CLI Contributors
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
22
+
23
+ ================================================================================
24
+
25
+ DATA LICENSE
26
+
27
+ The astronomical catalog data used by this software is sourced from the OpenNGC
28
+ project (https://github.com/mattiaverga/OpenNGC) and is licensed under the
29
+ Creative Commons Attribution-ShareAlike 4.0 International License (CC-BY-SA-4.0).
30
+
31
+ OpenNGC License Terms:
32
+
33
+ - Copyright (c) Mattia Verga and OpenNGC contributors
34
+ - License: CC-BY-SA-4.0 (https://creativecommons.org/licenses/by-sa/4.0/)
35
+ - Source: https://github.com/mattiaverga/OpenNGC
36
+ - Database files: NGC.csv and associated catalog data
37
+
38
+ Attribution Requirements:
39
+ When using or redistributing this software, you must:
40
+
41
+ 1. Provide attribution to the OpenNGC project and Mattia Verga
42
+ 2. Include a link to the OpenNGC repository
43
+ 3. Indicate if changes were made to the catalog data
44
+ 4. Share any derivative works under the same CC-BY-SA-4.0 license
45
+
46
+ For full CC-BY-SA-4.0 license terms, see: https://creativecommons.org/licenses/by-sa/4.0/
47
+
48
+ ================================================================================
49
+
50
+ THIRD-PARTY DEPENDENCIES
51
+
52
+ This software uses the following third-party libraries, each with their own licenses:
53
+
54
+ - Skyfield: MIT License (https://github.com/skyfielders/python-skyfield)
55
+ - Pandas: BSD 3-Clause License (https://github.com/pandas-dev/pandas)
56
+ - NumPy: BSD 3-Clause License (https://github.com/numpy/numpy)
57
+ - PyTZ: MIT License (https://github.com/stub42/pytz)
58
+ - TimezoneFinder: MIT License (https://github.com/jannikmi/timezonefinder)
59
+ - tqdm: MIT License (https://github.com/tqdm/tqdm)
60
+
61
+ Please refer to each library's respective repository for their full license terms.
starteller_cli-1.0.0/PKG-INFO ADDED
@@ -0,0 +1,160 @@
1
+ Metadata-Version: 2.4
2
+ Name: starteller-cli
3
+ Version: 1.0.0
4
+ Summary: A command-line tool for astrophotographers to find optimal viewing times for deep sky objects
5
+ Author: ConnRaus
6
+ License: MIT
7
+ Project-URL: Homepage, https://github.com/ConnRaus/StarTeller-CLI
8
+ Project-URL: Repository, https://github.com/ConnRaus/StarTeller-CLI
9
+ Keywords: astronomy,astrophotography,telescope,deep-sky-objects,ngc,messier,observing,astronomical-calculations
10
+ Classifier: Development Status :: 4 - Beta
11
+ Classifier: Intended Audience :: Science/Research
12
+ Classifier: Topic :: Scientific/Engineering :: Astronomy
13
+ Classifier: License :: OSI Approved :: MIT License
14
+ Classifier: Programming Language :: Python :: 3
15
+ Classifier: Programming Language :: Python :: 3.8
16
+ Classifier: Programming Language :: Python :: 3.9
17
+ Classifier: Programming Language :: Python :: 3.10
18
+ Classifier: Programming Language :: Python :: 3.11
19
+ Classifier: Programming Language :: Python :: 3.12
20
+ Requires-Python: >=3.8
21
+ Description-Content-Type: text/markdown
22
+ License-File: LICENSE
23
+ Requires-Dist: pandas>=1.5.0
24
+ Requires-Dist: numpy>=1.21.0
25
+ Requires-Dist: pytz>=2022.1
26
+ Requires-Dist: timezonefinder>=6.0.0
27
+ Requires-Dist: tqdm>=4.60.0
28
+ Dynamic: license-file
29
+
30
+ # StarTeller-CLI
31
+
32
+ A comprehensive command-line tool for astrophotographers and telescope enthusiasts to find optimal viewing times for deep sky objects throughout the year.
33
+
34
+ Given your location, StarTeller calculates when each object in the NGC/IC/Messier catalogs reaches its highest point during astronomical darkness. It accounts for altitude, direction, and dark sky conditions to help you plan observation sessions.
35
+
36
+ ## Installation
37
+
38
+ ### Install from PyPI (Recommended)
39
+
40
+ ```bash
41
+ pip install starteller-cli
42
+ starteller
43
+ ```
44
+
45
+ That's it! The `starteller` command will be available in your terminal.
46
+
47
+ ### Install from Source (Development)
48
+
49
+ If you want to modify the code or install the latest development version:
50
+
51
+ ```bash
52
+ git clone https://github.com/ConnRaus/StarTeller-CLI.git
53
+ cd StarTeller-CLI
54
+ python -m venv venv
55
+ source venv/bin/activate # On Windows: venv\Scripts\activate
56
+ pip install .
57
+ starteller
58
+ ```
59
+
60
+ Or run directly without installing:
61
+
62
+ ```bash
63
+ git clone https://github.com/ConnRaus/StarTeller-CLI.git
64
+ cd StarTeller-CLI
65
+ pip install -r requirements.txt
66
+ python src/starteller_cli.py
67
+ ```
68
+
69
+ ## How it works
70
+
71
+ 1. Enter your coordinates (or use a saved location)
72
+ 2. Pick a catalog (Messier, NGC, IC, or all ~13,000 objects)
73
+ 3. Set minimum altitude and optional direction filter
74
+ 4. Get a CSV with optimal viewing times for each object
75
+
76
+ The first run downloads the NGC catalog (~2MB) and calculates night darkness times for the year. Both are cached, so subsequent runs are fast.
77
+
78
+ ## Output
79
+
80
+ Results go to `starteller_output/` in your current directory. The CSV includes:
81
+
82
+ | Column | Description |
83
+ | ------------------------ | ------------------------------------------- |
84
+ | Object | NGC/IC/Messier ID |
85
+ | Name | Common name if available |
86
+ | Type | Galaxy, Nebula, Cluster, etc. |
87
+ | Best_Date | Date when object is highest at midnight |
88
+ | Best_Time_Local | Time of peak altitude |
89
+ | Max_Altitude_deg | Maximum altitude reached |
90
+ | Azimuth_deg | Azimuth angle at peak altitude |
91
+ | Direction | Cardinal direction (N, NE, E, etc.) |
92
+ | Rise_Time_Local | When it rises above your minimum altitude |
93
+ | Rise_Direction | Direction it rises from |
94
+ | Set_Time_Local | When it drops below minimum altitude |
95
+ | Set_Direction | Direction it sets toward |
96
+ | Observing_Duration_Hours | Total time above minimum altitude |
97
+ | Dark_Nights_Per_Year | Number of nights with astronomical darkness |
98
+ | Good_Viewing_Periods | Number of good viewing periods |
99
+ | Dark_Start_Local | Start of astronomical darkness |
100
+ | Dark_End_Local | End of astronomical darkness |
101
+ | Timezone | Timezone used for local times |
102
+
103
+ ## Options
104
+
105
+ **Catalogs:**
106
+
107
+ - Messier (~110 objects)
108
+ - NGC (~8,000 objects)
109
+ - IC (~5,000 objects)
110
+ - All (~13,000 objects)
111
+
112
+ **Filters:**
113
+
114
+ - Minimum altitude (default 20°)
115
+ - Direction filter - e.g., `90,180` for objects in the East to South
116
+
117
+ ## Python API
118
+
119
+ You can also use StarTeller programmatically:
120
+
121
+ ```python
122
+ from src.starteller_cli import StarTellerCLI
123
+
124
+ st = StarTellerCLI(
125
+ latitude=40.7,
126
+ longitude=-74.0,
127
+ elevation=10,
128
+ catalog_filter='messier'
129
+ )
130
+
131
+ results = st.find_optimal_viewing_times(min_altitude=25)
132
+ results = st.find_optimal_viewing_times(direction_filter=(90, 180)) # East to South
133
+ ```
134
+
135
+ ## File locations
136
+
137
+ Data is stored in platform-specific directories:
138
+
139
+ **Windows:** `%LOCALAPPDATA%\StarTeller-CLI\`
140
+ **Linux:** `~/.local/share/starteller-cli/`
141
+ **macOS:** `~/Library/Application Support/StarTeller-CLI/`
142
+
143
+ Cache goes to the platform's cache directory. Output CSVs go to `./starteller_output/`.
144
+
145
+ ## Requirements
146
+
147
+ - Python 3.8+
148
+ - Internet connection (first run only, to download catalog)
149
+
150
+ Dependencies: pandas, numpy, pytz, timezonefinder, tqdm
151
+
152
+ ## Data source
153
+
154
+ Catalog data comes from [OpenNGC](https://github.com/mattiaverga/OpenNGC) by Mattia Verga, licensed under CC-BY-SA-4.0.
155
+
156
+ ## License
157
+
158
+ MIT. See [LICENSE](LICENSE).
159
+
160
+ The NGC catalog data is CC-BY-SA-4.0.
starteller_cli-1.0.0/README.md ADDED
@@ -0,0 +1,131 @@
1
+ # StarTeller-CLI
2
+
3
+ A comprehensive command-line tool for astrophotographers and telescope enthusiasts to find optimal viewing times for deep sky objects throughout the year.
4
+
5
+ Given your location, StarTeller calculates when each object in the NGC/IC/Messier catalogs reaches its highest point during astronomical darkness. It accounts for altitude, direction, and dark sky conditions to help you plan observation sessions.
6
+
7
+ ## Installation
8
+
9
+ ### Install from PyPI (Recommended)
10
+
11
+ ```bash
12
+ pip install starteller-cli
13
+ starteller
14
+ ```
15
+
16
+ That's it! The `starteller` command will be available in your terminal.
17
+
18
+ ### Install from Source (Development)
19
+
20
+ If you want to modify the code or install the latest development version:
21
+
22
+ ```bash
23
+ git clone https://github.com/ConnRaus/StarTeller-CLI.git
24
+ cd StarTeller-CLI
25
+ python -m venv venv
26
+ source venv/bin/activate # On Windows: venv\Scripts\activate
27
+ pip install .
28
+ starteller
29
+ ```
30
+
31
+ Or run directly without installing:
32
+
33
+ ```bash
34
+ git clone https://github.com/ConnRaus/StarTeller-CLI.git
35
+ cd StarTeller-CLI
36
+ pip install -r requirements.txt
37
+ python src/starteller_cli.py
38
+ ```
39
+
40
+ ## How it works
41
+
42
+ 1. Enter your coordinates (or use a saved location)
43
+ 2. Pick a catalog (Messier, NGC, IC, or all ~13,000 objects)
44
+ 3. Set minimum altitude and optional direction filter
45
+ 4. Get a CSV with optimal viewing times for each object
46
+
47
+ The first run downloads the NGC catalog (~2MB) and calculates night darkness times for the year. Both are cached, so subsequent runs are fast.
48
+
49
+ ## Output
50
+
51
+ Results go to `starteller_output/` in your current directory. The CSV includes:
52
+
53
+ | Column | Description |
54
+ | ------------------------ | ------------------------------------------- |
55
+ | Object | NGC/IC/Messier ID |
56
+ | Name | Common name if available |
57
+ | Type | Galaxy, Nebula, Cluster, etc. |
58
+ | Best_Date | Date when object is highest at midnight |
59
+ | Best_Time_Local | Time of peak altitude |
60
+ | Max_Altitude_deg | Maximum altitude reached |
61
+ | Azimuth_deg | Azimuth angle at peak altitude |
62
+ | Direction | Cardinal direction (N, NE, E, etc.) |
63
+ | Rise_Time_Local | When it rises above your minimum altitude |
64
+ | Rise_Direction | Direction it rises from |
65
+ | Set_Time_Local | When it drops below minimum altitude |
66
+ | Set_Direction | Direction it sets toward |
67
+ | Observing_Duration_Hours | Total time above minimum altitude |
68
+ | Dark_Nights_Per_Year | Number of nights with astronomical darkness |
69
+ | Good_Viewing_Periods | Number of good viewing periods |
70
+ | Dark_Start_Local | Start of astronomical darkness |
71
+ | Dark_End_Local | End of astronomical darkness |
72
+ | Timezone | Timezone used for local times |
73
+
74
+ ## Options
75
+
76
+ **Catalogs:**
77
+
78
+ - Messier (~110 objects)
79
+ - NGC (~8,000 objects)
80
+ - IC (~5,000 objects)
81
+ - All (~13,000 objects)
82
+
83
+ **Filters:**
84
+
85
+ - Minimum altitude (default 20°)
86
+ - Direction filter - e.g., `90,180` for objects in the East to South
87
+
88
+ ## Python API
89
+
90
+ You can also use StarTeller programmatically:
91
+
92
+ ```python
93
+ from src.starteller_cli import StarTellerCLI
94
+
95
+ st = StarTellerCLI(
96
+ latitude=40.7,
97
+ longitude=-74.0,
98
+ elevation=10,
99
+ catalog_filter='messier'
100
+ )
101
+
102
+ results = st.find_optimal_viewing_times(min_altitude=25)
103
+ results = st.find_optimal_viewing_times(direction_filter=(90, 180)) # East to South
104
+ ```
105
+
106
+ ## File locations
107
+
108
+ Data is stored in platform-specific directories:
109
+
110
+ **Windows:** `%LOCALAPPDATA%\StarTeller-CLI\`
111
+ **Linux:** `~/.local/share/starteller-cli/`
112
+ **macOS:** `~/Library/Application Support/StarTeller-CLI/`
113
+
114
+ Cache goes to the platform's cache directory. Output CSVs go to `./starteller_output/`.
115
+
116
+ ## Requirements
117
+
118
+ - Python 3.8+
119
+ - Internet connection (first run only, to download catalog)
120
+
121
+ Dependencies: pandas, numpy, pytz, timezonefinder, tqdm
122
+
123
+ ## Data source
124
+
125
+ Catalog data comes from [OpenNGC](https://github.com/mattiaverga/OpenNGC) by Mattia Verga, licensed under CC-BY-SA-4.0.
126
+
127
+ ## License
128
+
129
+ MIT. See [LICENSE](LICENSE).
130
+
131
+ The NGC catalog data is CC-BY-SA-4.0.
starteller_cli-1.0.0/pyproject.toml ADDED
@@ -0,0 +1,54 @@
1
+ [build-system]
2
+ requires = ["setuptools>=45", "wheel"]
3
+ build-backend = "setuptools.build_meta"
4
+
5
+ [project]
6
+ name = "starteller-cli"
7
+ version = "1.0.0"
8
+ description = "A command-line tool for astrophotographers to find optimal viewing times for deep sky objects"
9
+ readme = "README.md"
10
+ license = {text = "MIT"}
11
+ authors = [
12
+ {name = "ConnRaus"}
13
+ ]
14
+ classifiers = [
15
+ "Development Status :: 4 - Beta",
16
+ "Intended Audience :: Science/Research",
17
+ "Topic :: Scientific/Engineering :: Astronomy",
18
+ "License :: OSI Approved :: MIT License",
19
+ "Programming Language :: Python :: 3",
20
+ "Programming Language :: Python :: 3.8",
21
+ "Programming Language :: Python :: 3.9",
22
+ "Programming Language :: Python :: 3.10",
23
+ "Programming Language :: Python :: 3.11",
24
+ "Programming Language :: Python :: 3.12",
25
+ ]
26
+ requires-python = ">=3.8"
27
+ keywords = [
28
+ "astronomy",
29
+ "astrophotography",
30
+ "telescope",
31
+ "deep-sky-objects",
32
+ "ngc",
33
+ "messier",
34
+ "observing",
35
+ "astronomical-calculations",
36
+ ]
37
+ dependencies = [
38
+ "pandas>=1.5.0",
39
+ "numpy>=1.21.0",
40
+ "pytz>=2022.1",
41
+ "timezonefinder>=6.0.0",
42
+ "tqdm>=4.60.0",
43
+ ]
44
+
45
+ [project.scripts]
46
+ starteller = "src.starteller_cli:main"
47
+
48
+ [project.urls]
49
+ Homepage = "https://github.com/ConnRaus/StarTeller-CLI"
50
+ Repository = "https://github.com/ConnRaus/StarTeller-CLI"
51
+
52
+ [tool.setuptools.packages.find]
53
+ where = ["."]
54
+ include = ["src*"]
starteller_cli-1.0.0/setup.cfg ADDED
@@ -0,0 +1,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+
starteller_cli-1.0.0/src/__init__.py ADDED
@@ -0,0 +1,23 @@
1
+ """
2
+ StarTeller-CLI Source Package
3
+ =============================
4
+
5
+ Core source code for the StarTeller-CLI astrophotography planning tool.
6
+
7
+ Modules:
8
+ starteller_cli: Main application with observation planning algorithms
9
+ catalog_manager: NGC/IC catalog loading and management
10
+ """
11
+
12
+ __version__ = "1.0.0"
13
+ __author__ = "ConnRaus"
14
+
15
+ from .starteller_cli import StarTellerCLI, get_user_location, main
16
+ from .catalog_manager import load_ngc_catalog
17
+
18
+ __all__ = [
19
+ 'StarTellerCLI',
20
+ 'get_user_location',
21
+ 'main',
22
+ 'load_ngc_catalog'
23
+ ]