spherapy 0.2.0__py3-none-any.whl

spherapy/util/credentials.py

@@ -0,0 +1,131 @@
+"""Functions to fetch and store spacetrack credentials on the system."""
+
+import configparser
+import getpass
+
+import keyring
+import keyring.errors
+
+import spherapy
+
+# used to store/fetch the username in keyring (abuse of API)
+USERNAME_KEY = "spherapy_username"
+
+def fetchConfigCredentials(config:configparser.ConfigParser) -> dict[str, str|None]:
+	"""Fetch spacetrack credentials from config file.
+
+	Args:
+		config: ConfigParser object containing config fields
+
+	Returns:
+		dict containing username and password
+	"""
+	username = config['credentials'].get('SpacetrackUser')
+	if username == 'None':
+		username = None
+
+	password = config['credentials'].get('SpacetrackPasswd')
+	if password == 'None': 		# noqa: S105, password not hardcoded, just parsing empty config file
+		password = None
+
+	return {'user':username, 'passwd':password}
+
+def fetchKeyringCredentials() -> dict[str,str|None]:
+	"""Fetch spacetrack credentials from system keyring.
+
+	Returns:
+		dict containing username and password
+
+	Raises:
+		ValueError: If no system keyring exists
+	"""
+	username = _fetchUser()
+	if username is None:
+		return {'user':None, 'passwd':None}
+	password = _fetchPass(username)
+	return {'user':username, 'passwd':password}
+
+def _fetchUser() -> str|None:
+	try:
+		username = keyring.get_password(spherapy.service_name, USERNAME_KEY)
+	except keyring.errors.NoKeyringError:
+		raise ValueError('No Keyring exists on this machine: '
+							'did you forget to set env variable SPHERAPY_CONFIG_DIR '
+							'if using on a headless machine?') \
+							from keyring.errors.NoKeyringError
+	return username
+
+def _fetchPass(username:str) -> str|None:
+	try:
+		password = keyring.get_password(spherapy.service_name, username)
+	except keyring.errors.NoKeyringError:
+		raise ValueError('No Keyring exists on this machine: '
+							'did you forget to set env variable SPHERAPY_CONFIG_DIR') \
+							from keyring.errors.NoKeyringError
+	return password
+
+def _reloadCredentials(config_parser:configparser.ConfigParser|None=None):
+	if config_parser is None:
+		spherapy.spacetrack_credentials = fetchKeyringCredentials()
+	else:
+		spherapy.spacetrack_credentials = fetchConfigCredentials(config_parser)
+
+def storeCredentials(user:None|str=None, passwd:None|str=None) -> bool:
+	"""Store spacetrack credentials in system keyring.
+
+	Can set either username or password, but can't set a password without a username
+
+	Args:
+		user: [optional] username string
+		passwd: [optional] password string
+
+	Returns:
+		True if successfully stored
+
+	Raises:
+		KeyError: raised if trying to store a password without a username
+	"""
+	if user is not None:
+		keyring.set_password(spherapy.service_name, USERNAME_KEY, user)
+	else:
+		user = _fetchUser()
+		if user is None:
+			raise KeyError("Can't set a Spacetrack password without a username: "
+							"no existing username")
+	if passwd is not None:
+		keyring.set_password(spherapy.service_name, user, passwd)
+
+	# check stored credentials match input
+	stored_user = _fetchUser()
+	stored_pass = _fetchPass(stored_user) if stored_user is not None else None
+	if (stored_user == user and stored_pass == passwd):
+		_reloadCredentials()
+		return True
+
+	return False
+
+def clearCredentials() -> None:
+	"""Clear the stored spacetrack credentials.
+
+	Raises:
+		KeyError: If no credentials are currently stored.
+	"""
+	user = _fetchUser()
+	if user is not None:
+		keyring.delete_password(spherapy.service_name, user)
+	else:
+		raise KeyError("No stored USER - no credentials to delete.")
+	keyring.delete_password(spherapy.service_name, USERNAME_KEY)
+
+	_reloadCredentials()
+
+def createCredentials():
+	"""Script helper function to create and store credentials.
+
+	Called by command line script. Requires user input.
+	"""
+	user = input('Please enter your spacetrack username:')
+	passwd = getpass.getpass(prompt='Please enter your spacetrack password:')
+	print("These credentials are being saved in your system keyring") 	# noqa: T201 print needed
+	if not storeCredentials(user=user, passwd=passwd):
+		print("Could not save credentials in system keyring") 	# noqa: T201 print needed

spherapy/util/elements_u.py

@@ -0,0 +1,70 @@
+"""Utility functions for dealing with propagation element set strings."""
+
+from typing import TypedDict
+
+
+class ElementsLineDict(TypedDict):
+	"""TypedDict container for lines of an element set.
+
+	Attributes:
+		fields: list of each field of an element set line as strings
+		line_str: original whole line string of element set (no newline)
+	"""
+	fields: list[str]
+	line_str: str
+
+def split3LELineIntoFields(line:str) -> ElementsLineDict:
+	"""Create an ElementsLineDict from an element set line.
+
+	Args:
+		line: string
+
+	Returns:
+		ElementsLineDict
+	"""
+	fields = line.split()
+	# insert fields into and store original line in tle dict
+	line_dict:ElementsLineDict = {'fields':fields,
+							'line_str':line}
+
+	return line_dict
+
+def stringify3LEDict(tle_dict:dict[int, ElementsLineDict]) -> str:
+	r"""Turn an element set dict 3LE dict back into a \n delimited string."""
+	lines = [line_dict['line_str'] for line_dict in tle_dict.values()]
+	return '\n'.join(lines)
+
+def dictify3LEs(lines:list[str]) -> list[dict[int, ElementsLineDict]]:
+	"""Turn list of strings into list of dicts storing TLE info.
+
+	dict:
+		key: line number (0-2)
+		value: dict
+			key: 'fields' | 'line_str'
+			value: 'list of fields as strings' | original TLE line str
+	"""
+	if len(lines) == 0:
+		raise ValueError("No data")
+	if len(lines)%3 != 0:
+		# If not obvious what lines relate to eachother, can't make assumption -> abort.
+		raise ValueError('Incomplete TLEs present, aborting')
+
+	list_3les = []
+	tle:dict[int,ElementsLineDict] = {0:{'fields':[], 'line_str':''},
+			1:{'fields':[], 'line_str':''},
+			2:{'fields':[], 'line_str':''}}
+	for line in lines:
+		line_dict = split3LELineIntoFields(line)
+		# insert fields into and store original line in tle dict
+		tle_line_num = int(line_dict['fields'][0])
+		tle[tle_line_num] = line_dict
+
+		if tle_line_num == 2: 		# noqa: PLR2004
+			# store parsed tle
+			list_3les.append(tle.copy())
+			# empty dict
+			tle[0] = {'fields':[], 'line_str':''}
+			tle[1] = {'fields':[], 'line_str':''}
+			tle[2] = {'fields':[], 'line_str':''}
+
+	return list_3les

spherapy/util/epoch_u.py

@@ -0,0 +1,149 @@
+"""Utility functions for converting different epochs.
+
+Attributes:
+	GMST_epoch: [description]
+"""
+
+import datetime as dt
+import pathlib
+
+import numpy as np
+
+from spherapy.util import elements_u
+
+GMST_epoch = dt.datetime(2000, 1, 1, 12, 0, 0)
+
+
+def epoch2datetime(epoch_str: str) -> dt.datetime:
+	"""Converts a fractional epoch string to a datetime object.
+
+	Args:
+	epoch_str:	fractional year epoch
+
+	Returns:
+		equivalent datetime
+	"""
+	if not isinstance(epoch_str, str):
+		epoch_str = str(epoch_str)
+
+	year = int(epoch_str[:2])
+	if year < 50:  # noqa: PLR2004
+		year += 2000
+	else:
+		year += 1900
+
+	fractional_day_of_year = float(epoch_str[2:])
+
+	base = dt.datetime(year, 1, 1, tzinfo=dt.timezone.utc)
+	return base + dt.timedelta(days=fractional_day_of_year) - dt.timedelta(days=1)
+
+def epochEarlierThan(epoch_a:str, epoch_b:str) -> bool:
+	"""Check if epoch A is earlier than epoch B.
+
+	Args:
+		epoch_a: TLE epoch string A
+		epoch_b: TLE epoch string B
+
+	Returns:
+		True if epoch A is earlier than epoch B
+	"""
+	datetime_a = epoch2datetime(epoch_a)
+	datetime_b = epoch2datetime(epoch_b)
+	return datetime_a < datetime_b
+
+def epochLaterThan(epoch_a:str, epoch_b:str) -> bool:
+	"""Check if epoch A is later than epoch B.
+
+	Args:
+		epoch_a: TLE epoch string A
+		epoch_b: TLE epoch string B
+
+	Returns:
+		True if epoch A is later than epoch B
+	"""
+	datetime_a = epoch2datetime(epoch_a)
+	datetime_b = epoch2datetime(epoch_b)
+	return datetime_a > datetime_b
+
+def datetime2TLEepoch(date: dt.datetime) -> str:
+	"""Converts a datetime to a TLE epoch string.
+
+	Args:
+		date: Datetime object
+
+	Returns:
+		TLE epoch string, with fractional seconds
+	"""
+	tzinfo = date.tzinfo
+	year_str = str(date.year)[-2:]
+	day_str = str(date.timetuple().tm_yday).zfill(3)
+	fraction_str = str(
+		(date - dt.datetime(date.year, date.month, date.day, tzinfo=tzinfo)).total_seconds()
+		/ dt.timedelta(days=1).total_seconds()
+	)[1:]
+
+	return year_str + day_str + fraction_str
+
+
+def datetime2sgp4epoch(date: dt.datetime) -> float:
+	"""Converts a datetime to an sgp4 epoch.
+
+	Args:
+		date: Datetime object
+
+	Returns:
+		SGP4 epoch, with fractional seconds
+	"""
+	tzinfo = date.tzinfo
+	sgp4start = dt.datetime(1949, 12, 31, 0, 0, 0, tzinfo=tzinfo)
+	delta = date - sgp4start
+	return delta.days + delta.seconds / 86400
+
+
+def findClosestDatetimeIndices(test_arr:np.ndarray[tuple[int], np.dtype[np.datetime64]],
+								source_arr:np.ndarray[tuple[int], np.dtype[np.datetime64]]) \
+								-> np.ndarray[tuple[int], np.dtype[np.int64]]:
+	"""Find the index of the closest datetime in source arr for each datetime in test_arr.
+
+	Both search_arr and source_arr must be sorted.
+
+	Args:
+		test_arr: Mx1 array of datetimes, will find closest time for each element in this array
+		source_arr: Nx1: array of datetimes to compare to
+
+	Returns:
+		Mx1 array of indices of source_arr
+	"""
+	# convert to unix timestamps first to save memory
+	test_arr_fl = np.vectorize(lambda x:x.timestamp())(test_arr)
+	source_arr_fl = np.vectorize(lambda x:x.timestamp())(source_arr)
+	idx_arr = np.zeros(test_arr_fl.shape, dtype=np.int64)
+	for ii in range(len(test_arr_fl)):
+		diff = np.abs(source_arr_fl-test_arr_fl[ii])
+		idx_arr[ii] = np.argmin(diff,axis=0)
+
+	return idx_arr
+
+def getStoredEpochs(tle_path:pathlib.Path) -> None|tuple[dt.datetime, dt.datetime|None]:
+	"""Return the start and end epoch for tle_path.
+
+	Args:
+		tle_path: tle file
+
+	Returns:
+		(first epoch datetime, last epoch datetime)
+		None if no spacetrack tle stored for sat_id
+	"""
+	if not tle_path.exists():
+		return None
+
+	with tle_path.open('r') as fp:
+		lines = fp.readlines()
+
+	first_tle_line_1 = elements_u.split3LELineIntoFields(lines[1])
+	last_tle_line_1 = elements_u.split3LELineIntoFields(lines[-2])
+
+	first_epoch_dt = epoch2datetime(first_tle_line_1['fields'][3])
+	last_epoch_dt = epoch2datetime(last_tle_line_1['fields'][3])
+
+	return (first_epoch_dt, last_epoch_dt)

spherapy/util/exceptions.py

@@ -0,0 +1,7 @@
+"""Generic exceptions that apply throughout satplot."""
+
+class OutOfRangeError(Exception):
+	"""The value is out of the acceptable range."""
+
+class DimensionError(Exception):
+	"""Dimension of an array is invalid."""

spherapy/util/orbital_u.py

@@ -0,0 +1,72 @@
+"""Utility functions for orbital calculations."""
+import numpy as np
+
+import spherapy.util.constants as consts
+
+
+def ssoInc(alt:float, e:float=0) -> float:
+	# TODO: update to calculate for different central bodies
+	"""Generates required inclination for given altitude [km] to maintain Sun Syncrhonous orbit.
+
+	Args:
+		alt: altitude of orbit in km
+		e: [Optional] eccentricity of orbit
+			Default is circular (0)
+
+	Returns:
+		Inclination angle in degrees
+	"""
+	a = consts.R_EARTH + alt * 1e3
+	# print(a)
+	p = a * (1 - e**2)
+	# print(p)
+	period = 2 * np.pi * np.sqrt(a**3 / consts.GM_EARTH)
+	# print(period)
+	req_prec_rate = (2 * np.pi / 365.25) * (1 / 86400.)
+	# print(req_prec_rate)
+	req_prec_orb = req_prec_rate * period
+	# print(req_prec_orb)
+
+	cosi = (req_prec_orb * p**2) / (-3 * np.pi * consts.J2 * consts.R_EARTH**2)
+	# print(cosi)
+
+	inc = np.arccos(cosi)
+
+	return np.rad2deg(inc)
+
+
+def calcPeriod(a:float) -> float:
+	"""Returns the period of an elliptical or circular orbit.
+
+	Args:
+		a: semi-major axis in m
+
+	Returns:
+		Orbital period in s
+	"""
+	return 2 * np.pi * np.sqrt(a**3 / consts.GM_EARTH)
+
+def calcOrbitalVel(a:float, pos:np.ndarray[tuple[int],np.dtype[np.float64]]) -> float:
+	"""Return the instantaneous velocity magnitude for an elliptical orbit at position.
+
+	Args:
+		a: semi-major axis in m
+		pos: cartesian position, assuming the origin is at the central body.
+
+	Returns:
+		instantaneous velocity magnitude.
+	"""
+	r = np.linalg.norm(pos)
+
+	return np.sqrt(consts.GM_EARTH * (2 / r - 1 / a))
+
+def calcMeanMotion(a:float) -> float:
+	"""Returns mean motion [radians/s] for an elliptical or circular orbit with semi-major axis a.
+
+	Args:
+		a: semi-major axis in m
+
+	Returns:
+		Orbital period in s
+	"""
+	return np.sqrt(consts.GM_EARTH / a**3)

spherapy/util/spacetrack.py

@@ -0,0 +1,272 @@
+"""Functions to fetch TLEs from Spacetrack.
+
+Attributes:
+	MAX_RETRIES: number of times to try and reach Spacetrack.
+"""
+
+import datetime as dt
+import logging
+import pathlib
+
+from typing import TypedDict
+from typing_extensions import NotRequired
+
+import spacetrack as sp
+
+import spherapy
+from spherapy.util import elements_u, epoch_u
+
+MAX_RETRIES=3
+
+logger = logging.getLogger(__name__)
+
+class _TLEGetter:
+	"""Container around python spacetrack library."""
+	def __init__(self, sat_id_list:list[int], user:None|str=None, passwd:None|str=None):
+		# initialise the client
+		if user is None:
+			self.username = spherapy.spacetrack_credentials['user']
+		else:
+			self.username = user
+		if passwd is None:
+			self.password = spherapy.spacetrack_credentials['passwd']
+		else:
+			self.password = passwd
+		if self.username is None or self.password is None:
+			raise InvalidCredentialsError('No Spacetrack Credentials have been entered')
+
+		self.modified_ids = []
+		try:
+			self.stc = sp.SpaceTrackClient(self.username, self.password)
+			for sat_id in sat_id_list:
+				logger.info("Trying to update TLEs for %s", sat_id)
+				if not self.checkTLEFileExists(sat_id) or self.getNumPastTLEs(sat_id) == 0:
+					res = self.fetchAll(sat_id)
+					if res is not None:
+						self.modified_ids.append(res)
+				else:
+					res = self.fetchLatest(sat_id)
+					if res is not None:
+						self.modified_ids.append(res)
+
+		except sp.AuthenticationError:
+			raise InvalidCredentialsError('Username and password are incorrect!') from sp.AuthenticationError 	#noqa: E501
+
+	def getModifiedIDs(self) -> list[int]:
+		return self.modified_ids
+
+	def checkTLEFileExists(self, sat_id:int) -> bool:
+		return getTLEFilePath(sat_id).exists()
+
+	def fetchAll(self, sat_id:int) -> int|None:
+		"""Fetch all TLEs for sat_id.
+
+		Args:
+			sat_id: satcat id to fetch
+
+		Returns:
+			sat_id if succesfully fetched
+			None if couldn't fetch
+		"""
+		attempt_number = 0
+		while attempt_number < MAX_RETRIES:
+			try:
+				opts = self._calcRequestAllOptions(sat_id)
+				logger.info("Requesting TLEs from spacetrack with following options: %s", opts)
+				resp_line_iterator = self.stc.tle(**opts)
+				resp_lines = list(resp_line_iterator)
+				tle_dict_list = elements_u.dictify3LEs(resp_lines)
+				self._writeTLEsToNewFile(sat_id, tle_dict_list)
+				break
+			except TimeoutError:
+				attempt_number += 1
+
+		if attempt_number == MAX_RETRIES:
+			logger.error("Could not fetch All TLEs for sat %s: failed %s times.",
+							sat_id, attempt_number)
+			return None
+
+		return sat_id
+
+	def getNumPastTLEs(self, sat_id:int) -> int:
+		"""Retrieve number of TLEs stored for sat_id."""
+		with getTLEFilePath(sat_id).open('r') as fp:
+			lines = fp.readlines()
+		return int(len(lines)/3)
+
+	def fetchLatest(self, sat_id:int) -> int|None:
+		"""Fetch the latest TLEs for sat_id, and append them to the TLE file.
+
+		Args:
+			sat_id: satcat id to fetch
+
+		Returns:
+			sat_id if succesfully fetched
+			None if couldn't fetch
+		"""
+		attempt_number = 0
+		while attempt_number < MAX_RETRIES:
+			try:
+				_, days_since_last_epoch = self._findLocalLastEpoch(sat_id)
+				if days_since_last_epoch > 0.0:
+					opts = self._calcRequestPartialOptions(sat_id)
+					logger.info("Requesting TLEs from spacetrack with following options: %s", opts)
+					resp_line_iterator = self.stc.tle(**opts)
+					resp_lines = list(resp_line_iterator)
+					tle_dict_list = elements_u.dictify3LEs(resp_lines)
+					self._writeTLEsToFile(sat_id, tle_dict_list)
+				break
+			except TimeoutError:
+				attempt_number += 1
+		if attempt_number == MAX_RETRIES:
+			logger.error("Could not fetch the latest TLEs for sat %s: failed %s times.",
+							sat_id, attempt_number)
+			raise TimeoutError(f"Could not fetch the latest TLEs for sat {sat_id}: "
+								f"failed {attempt_number} times.")
+
+		return sat_id
+
+	def _findLocalLastEpoch(self, sat_id:int) -> tuple[str, float]:
+		"""Find the last TLE epoch in a TLE file."""
+		# get penultimate and ultimate epochs
+		with getTLEFilePath(sat_id).open('r') as fp:
+			lines = fp.readlines()
+		while lines[-1] == '':
+			lines = lines[:-1]
+		last_epoch_line = lines[-2]
+		last_tle_epoch = last_epoch_line.split()[3]
+
+		last_epoch_datetime = epoch_u.epoch2datetime(last_tle_epoch)
+		delta = dt.datetime.now(tz=dt.timezone.utc) - last_epoch_datetime
+
+		return last_tle_epoch, delta.days
+
+	def _calcRequestAllOptions(self, sat_id:int) -> "_RequestOptions":
+		"""Format spacetrack library request options. Request all TLEs."""
+		request_options:_RequestOptions = {
+				'norad_cat_id': sat_id,
+				'orderby': 'epoch asc',
+				'limit': 500000,
+				'format': '3le',
+				'iter_lines': True}
+
+		return request_options
+
+	def _calcRequestPartialOptions(self, sat_id:int) -> "_RequestOptions":
+		"""Format spacetrack library request options. Request all TLEs since last epoch."""
+		_, days_since_last_epoch = self._findLocalLastEpoch(sat_id)
+
+		request_options:_RequestOptions = {
+				'norad_cat_id': sat_id,
+				'orderby': 'epoch asc',
+				'epoch': f'>now-{days_since_last_epoch+1}',
+				'limit': 500000,
+				'format': '3le',
+				'iter_lines': True}
+
+		return request_options
+
+	def _writeTLEsToFile(self, sat_id:int,
+								tle_dict_list:list[dict[int, elements_u.ElementsLineDict]]):
+		"""Append TLEs to TLE file."""
+		last_epoch, _ = self._findLocalLastEpoch(sat_id)
+		first_new_idx = None
+		for tle_idx, tle_dict in enumerate(tle_dict_list):
+			epoch = tle_dict[1]['fields'][3]
+			if epoch_u.epochLaterThan(epoch, last_epoch):
+				first_new_idx = tle_idx
+				break
+		if first_new_idx is not None:
+			with getTLEFilePath(sat_id).open('a') as fp:
+				for tle_dict in tle_dict_list[first_new_idx:]:
+					fp.write('\n')
+					fp.write(elements_u.stringify3LEDict(tle_dict))
+
+	def _writeTLEsToNewFile(self, sat_id:int,
+									tle_dict_list:list[dict[int, elements_u.ElementsLineDict]]):
+		"""New TLE, write entire content to new file."""
+		with getTLEFilePath(sat_id).open('w') as fp:
+			# don't want to begin or end file with newline
+			fp.write(elements_u.stringify3LEDict(tle_dict_list[0]))
+			for tle_dict in tle_dict_list[1:]:
+				fp.write('\n')
+				fp.write(elements_u.stringify3LEDict(tle_dict))
+
+class InvalidCredentialsError(Exception):
+	"""Error indicating invalid credentials used to access spacetrack."""
+	def __init__(self, message:str): # noqa: D107
+		super().__init__(message)
+
+class _RequestOptions(TypedDict):
+	norad_cat_id: int
+	orderby: str
+	epoch: NotRequired[str]
+	limit: int
+	format: str
+	iter_lines: bool
+
+def updateTLEs(sat_id_list:list[int], user:None|str=None, passwd:None|str=None) -> list[int]:
+	"""Fetch most recent TLE for satcat IDs from spacetrack.
+
+	Fetch most recent TLEs for provided list of satcat IDs, and append to file.
+		If no TLE file yet exists, will download all historical TLEs
+	Will try MAX_RETRIES before raising a TimeoutError
+
+	Args:
+		sat_id_list: list of satcat ids to fetch
+		user: [Optional] overriding spacetrack username to use
+		passwd: [Optional] overriding spacetrack password to use
+
+	Returns:
+		list:list of satcat ids successfully fetched
+
+	Raises:
+		TimeoutError
+	"""
+	logger.info("Using SPACETRACK to update TLEs")
+	g = _TLEGetter(sat_id_list,user=user,passwd=passwd)
+
+	return g.getModifiedIDs()
+
+def getTLEFilePath(sat_id:int) -> pathlib.Path:
+	"""Gives path to file where spacetrack TLE is stored.
+
+	Spacetrack TLEs are stored in {satcadID}.tle
+
+	Args:
+		sat_id: satcat ID
+
+	Returns:
+		path to file
+	"""
+	return spherapy.tle_dir.joinpath(f'{sat_id}.tle')
+
+def getStoredEpochs(sat_id:int) -> None|tuple[dt.datetime, dt.datetime|None]:
+	"""Return the start and end epoch for {sat_id}.tle .
+
+	Args:
+		sat_id: satcat id to check
+
+	Returns:
+		(first epoch datetime, last epoch datetime)
+		None if no spacetrack tle stored for sat_id
+	"""
+	tle_path = getTLEFilePath(sat_id)
+
+	return epoch_u.getStoredEpochs(tle_path)
+
+
+def doCredentialsExist() -> bool:
+	"""Checks if spacetrack credentials have been loaded into Spherapy.
+
+	Returns:
+		bool:
+	"""
+	user_stored = False
+	passwd_stored = False
+	if spherapy.spacetrack_credentials['user'] is not None:
+		user_stored = True
+	if spherapy.spacetrack_credentials['passwd'] is not None:
+		passwd_stored = True
+
+	return (user_stored and passwd_stored)