Metadata-Version: 2.1
Name: suntimes
Version: 0.2.2
Summary: For a given place (longitude, latitude and altitude) and a given day, returns the time of sunrise and the time of sunset (in UTC and in local time). Create and save a json or csv file with the timetables for a whole year.
Home-page: https://github.com/p-mathis/suntimes
Author: Paul Mathis
Author-email: pmathis@protonmail.com
License: UNKNOWN
Platform: UNKNOWN
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.6
Description-Content-Type: text/markdown
Requires-Dist: pytz
Requires-Dist: tzlocal
Requires-Dist: jdcal

# SunTimes : longitude, latitude and altitude
Sunrise and sunset time calculation for a location (longitude, latitude, altitude) with python. Also available sunrise and sunset timetable for a whole year as a json or a csv file.
## Project description
This module contains functions to determine the time of sunset and the time of sunrise for a given day in a given location (longitude, latitude and altitude).  
Times are calculated using data from [Wikipedia](https://en.wikipedia.org/wiki/Sunrise_equation).  
The main functions return the times of sunset and sunrise in UTC or in local time. Additional functions return separately the hour, minute and second of sunrise and sunset. A function returns the length of the day. It is possible to obtain the timetables for a place in a different timezone, just by specifying this one.  
The SunFiles class allows you to create and save a json or csv file with the timetables for a whole year.
## Installation
### Required modules
suntimes module requires pytz, tzlocal, jdcal  
```sh
$ pip install pytz
```
```sh
$ pip install tzlocal
```
```sh
$ pip install jdcal
```
### Installation
The module can be installed using pip
```sh
$ pip install suntimes
 ```
## Usage
### Class SunTimes
```python
place = SunTimes(longitude, latitude, altitude=0)
```
A place is characterized by longitude, latitude, altitude
- longitude: float between -180 and 180; negative for west longitudes, positive for east longitudes
- latitude: float between -66.56 and +66.56; the calculation is only valid between the two polar circles. Positive if north, negative if south
- altitude: float, in meters; greater than or equal to zero. Default = 0.
### Methods
Most of mehtods take a date as an argument.  
The date will be a datetime.datetime in the format (yyyy, mm, dd), the time not important. Eg : datetime(2020, 12, 22).  
Methods risewhere and setwhere take timezone as a second argument.  
The timezone list is available on [github](https://gist.github.com/heyalexej/8bf688fd67d7199be4a1682b3eec7568).
### Examples
#### Main methods
Import modules. Create an instance.
```python
from datetime import datetime
from suntimes import SunTimes

#date
day = datetime(2021,1,6)
#location Paris Notre-Dame France
sun = SunTimes(2.349902, 48.852968, 35)
```
Return UTC time :  
```python
sun.riseutc(day)
datetime.datetime(2021, 1, 6, 7, 42, 52, 269)
```
```python
sun.setutc(day)
datetime.datetime(2021, 1, 6, 16, 12, 5, 630)
```
Return local computer time : 
```python
sun.riselocal(day)
datetime.datetime(2021, 1, 6, 8, 42, 52, 269, tzinfo=<DstTzInfo 'Europe/Paris' CET+1:00:00 STD>)
```
```python
sun.setlocal(day)
datetime.datetime(2021, 1, 6, 17, 12, 5, 630, tzinfo=<DstTzInfo 'Europe/Paris' CET+1:00:00 STD>)
```
#### Separately hour, minute, second (local computer time)
```python
sun.hrise(day)
8
sun.mrise(day)
42
sun.srise(day)
52
sun.hset(day)
17
sun.mset(day)
12
sun.sset(day)
5
```
#### Duration of the day
Return the length of the day in a datetime.timedelta format, a tuple or a verbose format
```python
sun.durationdelta(day)
datetime.timedelta(seconds=30553, microseconds=361)
sun.durationtuple(day)
(8, 29, 13, 0)
sun.durationverbose(day)
'8h 29mn 13s'
```
#### Suntimes choosing the timezone
Sunrise and sunset in Sao Paulo (Brazil)  
```python
#location Sao Paulo, Brazil
sun = SunTimes(-46.63611, -23.5475, 769)
#sunrise and sunset in Sao Paulo, local computer time (France)
sun.riselocal(day)
datetime.datetime(2021, 1, 6, 9, 23, 20, 849, tzinfo=<DstTzInfo 'Europe/Paris' CET+1:00:00 STD>)
sun.setlocal(day)
datetime.datetime(2021, 1, 6, 23, 3, 37, 361, tzinfo=<DstTzInfo 'Europe/Paris' CET+1:00:00 STD>)
# sunrise and sunset in Sao Paulo, Sao Paulo time
sun.risewhere(day, 'America/Sao_Paulo')
datetime.datetime(2021, 1, 6, 5, 23, 20, 849, tzinfo=<DstTzInfo 'America/Sao_Paulo' -03-1 day, 21:00:00 STD>)
sun.setwhere(day, 'America/Sao_Paulo')
datetime.datetime(2021, 1, 6, 19, 3, 37, 361, tzinfo=<DstTzInfo 'America/Sao_Paulo' -03-1 day, 21:00:00 STD>)
```
#### Influence of altitude
Altitude can have an influence on the result.
For example considering Mount Everst :  
```python
# Mount Everest, altitude = default (zero)
sun_0 = SunTimes(86.9246, 27.9891)
# Mount Everest, altitude = 8848
sun_8848 = SunTimes(86.9246, 27.9891, 8848)
# duration of the day, sun_0 and sun_8848
sun_0.durationverbose(day)
'10h 26mn 33s'
sun_8848.durationverbose(day)
'10h 58mn 54s'  
```
A difference of more than half an hour for the calculation of the length of the day.
## Class SunFiles
file = SunFiles(place, year, place_verbose=""), where place is a SunTimes instance, year the year you choose and place_verbose the verbose name of the place.  
### Instantiation
```python
from suntimes import SunTimes, SunFiles

place = SunTimes(2.349902, 48.852968, 35)
file = SunFiles(place, 2020, "Notre-Dame de Paris")
```
### Methods
#### Get the data
```python
place = SunTimes(2.349902, 48.852968, 35)
file = SunFiles(place, 2020, "Notre-Dame de Paris")
# Get json data : get_json(self, elsewhere = None)
file.get_json()
# Get csv data : get_csv(self, elsewhere = None)
file.get_csv(elsewhere = "America/Sao_Paulo")
```
Return data with:
- month
- day
- hour, minute and second of sunrise and sunset in utc, local computer time and specific timezone. If elswhere not specified, return utc, local computer time, local computer time again.
- schedules in a verbose mode (i.e. 8 h 12 mn 7 s)
#### Create and save the file
The data is calculated and the file created and saved.
```python
register_json(self, path=None, file_name=None, elswhere=None)
register_csv(self, path=None, file_name=None, elswhere=None)
```
The path must be indicated correctly, otherwise an error is raised : "/home/foo/Desktop/" or "C:\Documents\Foo\Exercices\ for exemple.
If file_name is not specified, it is generated automatically. For example : "2020_Notre-Dame_de_Paris_sun_timetable.csv"
```python
file.register_json(path="/home/foo/Desktop/", file_name="2020.json")
file.register_csv(path="/home/foo/Desktop/", elsewhere="America/Sao_Paulo")
```
#### Read the file as a workbook
- CSV file is easy to open on a Excel xlsx or any other workbook.
- JSON file can be converted to xlsx [here](https://codebeautify.org/json-to-excel-converter).

