**illumipy** is a Python module for estimating outside Illumination levels for given location, date and time.
Requires an OpenWeatherMap [APIkey](https://openweathermap.org/appid)
## Features
- Provides an estimation of outside brightness level based on weather and astronomical data, location, time and empirical model.
- Calculates a variety of solar parameters that can be used for prediction of solar irradiance and solar energy production
- Can be adjustes for date, time, location, cloud coverage and many more.
- Can be used as imported Python module or accessed directly over CLI with a range of useful options
- Uses the free OpenWeatherMap API
## INSTALLATION
Installation is easiest using a package manager like [PIP](https://pip.pypa.io/en/stable/ ). To install pip run:
```bash
python -m ensurepip --upgrade
```
To install illumipy with pip, run:
```bash
pip install illumipy
```
Source files can be found on [GitHub](https://github.com/duckwilliam/illumipy), in case you want to tell install manually.
This package can be used via import function in Python or be run directly as a script with CLI options:
### Import
```python
import illumipy
# Create Illumination object using light_data() and pass options
illumipy.data.light_data([OPTIONS])
```
To use the module, simply import illumipy and call the function
data.light_data(): This returns a dictionary object with
the following information:
+ ['illuminance']: Outside Brightness in Lux
+ ['time']: Time used as %-H (e.g. 4 or ~~12)
+ ['date']: Date used as YYYY-MM-DD
+ ['city']: City Used
+ ['country']: Country Used
+ ['cloud_coverage']: Cloud coverage in %
+ ['et_illuminance']: Extraterrestrial Illuminance in Lux
+ ['direct_illuminance']: Direct Illuminance in Lux
+ ['horizontal_illuminance']: Horizontal Illuminance in Lux
+ ['horizontal_sky_illuminance']: Horizontal Sky Illuminance in Lux
+ ['sunrise']: Time of Sunrise as hh:mm
+ ['sunset']: Time of sunset as hh:mm
+ ['sun_altitude']: Sund altitude at [Time] in degrees.
+ ['day']: True if there is daylight at [Time].
+ ['clear_sky_index'] = Aproximation of Clear Sky Index based on cloud coverage
+ ['cs_irradiance'] = Estimated Clear Sky Irradiance in W/m^2 based on solar altitude.
+ ['irradiance'] = Estimated current Irradiance in W/m^2 based on solar altitude and cloud coverage.
+ coverage.
+ ['air_mass'] = calculated air mass for given solar altitude, based on empirical model.
+ ['azimuth'] = Calculated solar azimuth for given time and location.
+ ['declination'] = calculated solar declination angle for given date.
+ ['LSTM'] = Local standard time meridian in degrees.
+ ['EOT'] = Equation of Time.
It Takes the following arguments:
+ time: str=[0-24]
+ date: str=[YYYY-MM-DD]
+ city: str=['City']
+ country: str=['Country']
+ api_key: str=['api_key']
+ cloud_coverage: int=[0-100]
*if no arguments are provided, defaults to values defined in defaults.py*
### Command line
To use as script with CLI run <python -m illumipy>.
To get a list of available CLI options run <
```bash
python -m illumipy -h
> usage: __main__.py [-h] [-t TIME] [-d DATE] [-c CITY]
[-C COUNTRY] [-a API]
[-o OUTPUT [OUTPUT ...]] [-D] [-v] [-A] [-s]
General-purpose solar brightness calculator.
options:
-h, --help show this help message and exit
-t TIME, --time TIME Time of the day in hours (0-24, e.g. 4
or 12). Defaults to current time if not
specified.
-d DATE, --date DATE Date as YYYY-MM-DD (e. g. 2023-06-01).
Defaults to current date if not
specified.
-c CITY, --city CITY City name (e. g. Berlin). Defaults to
{CITY_DEFAULT} if not specified.
-C COUNTRY, --Country COUNTRY
Country name (e. g. Germany). Defaults
to {COUNTRY_DEFAULT} if not specified.
-a API, --api API OpeWeather API-Key (required).
Alternatively, a default API key can be
defined in main.py
-o OUTPUT [OUTPUT ...], --output OUTPUT [OUTPUT ...]
Define the parameters to be returned.
Defaults to 'Illuminance' if not
specified. To see available values try
illumipy [-o|--output] help
-D, --debug Print lots of debugging statements
-v, --verbose Be verbose
-A, --all Print out entire dataset. Default is
just the Illuminance in Lux
-s, --short Print only values, no description
```
## Current issues
- cloud level, sunrise and sunset are not available for dates in the past. Results might therefore be unreliable. Times for sunrise and sunset will always be for the current day.
- ~~at 100% cloud coverage, Results might be unreliable.~~
## Requirements
- Python3
- Python packages:
- requests
- logging
- math
- sys
- datetime
- argparse
- OpenWeatherMap API-Key
## About
Author: Kalle Fornia
GitHub: https://github.com/duckwilliam/illumipy
PyPi: https://pypi.org/project/illumipy
Version: 1.3.1
10/2023
Raw data
{
"_id": null,
"home_page": "https://github.com/duckwilliam/illumipy",
"name": "illumipy",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.11,<4.0",
"maintainer_email": "",
"keywords": "solar,illumination,sun,sunrise,sunset,sunlight,sunrise-sunset,OpenWeatherMap,brightness,light",
"author": "Kalle Fornia",
"author_email": "kallefornia@tuta.io",
"download_url": "https://files.pythonhosted.org/packages/50/f6/74ca7df0dd972a2f31338174d76fb5a9ae119b3e712f0be45e954b41d01c/illumipy-1.4.26.tar.gz",
"platform": null,
"description": "**illumipy** is a Python module for estimating outside Illumination levels for given location, date and time.\nRequires an OpenWeatherMap [APIkey](https://openweathermap.org/appid)\n\n## Features\n- Provides an estimation of outside brightness level based on weather and astronomical data, location, time and empirical model.\n- Calculates a variety of solar parameters that can be used for prediction of solar irradiance and solar energy production\n- Can be adjustes for date, time, location, cloud coverage and many more.\n- Can be used as imported Python module or accessed directly over CLI with a range of useful options\n- Uses the free OpenWeatherMap API\n\n## INSTALLATION\n\nInstallation is easiest using a package manager like [PIP](https://pip.pypa.io/en/stable/ ). To install pip run:\n```bash\npython -m ensurepip --upgrade \n```\n\nTo install illumipy with pip, run:\n```bash\npip install illumipy \n```\n\nSource files can be found on [GitHub](https://github.com/duckwilliam/illumipy), in case you want to tell install manually. \n This package can be used via import function in Python or be run directly as a script with CLI options:\n\n### Import\n```python\nimport illumipy\n# Create Illumination object using light_data() and pass options\nillumipy.data.light_data([OPTIONS]) \n```\nTo use the module, simply import illumipy and call the function\ndata.light_data(): This returns a dictionary object with\nthe following information:\n+ ['illuminance']: Outside Brightness in Lux\n+ ['time']: Time used as %-H (e.g. 4 or ~~12)\n+ ['date']: Date used as YYYY-MM-DD\n+ ['city']: City Used\n+ ['country']: Country Used\n+ ['cloud_coverage']: Cloud coverage in %\n+ ['et_illuminance']: Extraterrestrial Illuminance in Lux\n+ ['direct_illuminance']: Direct Illuminance in Lux\n+ ['horizontal_illuminance']: Horizontal Illuminance in Lux\n+ ['horizontal_sky_illuminance']: Horizontal Sky Illuminance in Lux\n+ ['sunrise']: Time of Sunrise as hh:mm\n+ ['sunset']: Time of sunset as hh:mm\n+ ['sun_altitude']: Sund altitude at [Time] in degrees.\n+ ['day']: True if there is daylight at [Time].\n+ ['clear_sky_index'] = Aproximation of Clear Sky Index based on cloud coverage\n+ ['cs_irradiance'] = Estimated Clear Sky Irradiance in W/m^2 based on solar altitude.\n+ ['irradiance'] = Estimated current Irradiance in W/m^2 based on solar altitude and cloud coverage.\n+ coverage.\n+ ['air_mass'] = calculated air mass for given solar altitude, based on empirical model.\n+ ['azimuth'] = Calculated solar azimuth for given time and location.\n+ ['declination'] = calculated solar declination angle for given date.\n+ ['LSTM'] = Local standard time meridian in degrees.\n+ ['EOT'] = Equation of Time.\n\nIt Takes the following arguments:\n+ time: str=[0-24]\n+ date: str=[YYYY-MM-DD]\n+ city: str=['City']\n+ country: str=['Country']\n+ api_key: str=['api_key']\n+ cloud_coverage: int=[0-100] \n\n*if no arguments are provided, defaults to values defined in defaults.py* \n\n### Command line \nTo use as script with CLI run <python -m illumipy>.\nTo get a list of available CLI options run <\n```bash\npython -m illumipy -h\n> usage: __main__.py [-h] [-t TIME] [-d DATE] [-c CITY]\n [-C COUNTRY] [-a API]\n [-o OUTPUT [OUTPUT ...]] [-D] [-v] [-A] [-s]\n\nGeneral-purpose solar brightness calculator.\n\noptions:\n -h, --help show this help message and exit\n -t TIME, --time TIME Time of the day in hours (0-24, e.g. 4\n or 12). Defaults to current time if not\n specified.\n -d DATE, --date DATE Date as YYYY-MM-DD (e. g. 2023-06-01).\n Defaults to current date if not\n specified.\n -c CITY, --city CITY City name (e. g. Berlin). Defaults to\n {CITY_DEFAULT} if not specified.\n -C COUNTRY, --Country COUNTRY\n Country name (e. g. Germany). Defaults\n to {COUNTRY_DEFAULT} if not specified.\n -a API, --api API OpeWeather API-Key (required).\n Alternatively, a default API key can be\n defined in main.py\n -o OUTPUT [OUTPUT ...], --output OUTPUT [OUTPUT ...]\n Define the parameters to be returned.\n Defaults to 'Illuminance' if not\n specified. To see available values try\n illumipy [-o|--output] help\n -D, --debug Print lots of debugging statements\n -v, --verbose Be verbose\n -A, --all Print out entire dataset. Default is\n just the Illuminance in Lux\n -s, --short Print only values, no description\n```\n \n## Current issues\n- cloud level, sunrise and sunset are not available for dates in the past. Results might therefore be unreliable. Times for sunrise and sunset will always be for the current day.\n\n- ~~at 100% cloud coverage, Results might be unreliable.~~ \n\n## Requirements\n- Python3\n- Python packages:\n - requests\n - logging\n - math\n - sys\n - datetime\n - argparse\n- OpenWeatherMap API-Key\n\n## About\nAuthor: Kalle Fornia \nGitHub: https://github.com/duckwilliam/illumipy \nPyPi: https://pypi.org/project/illumipy \nVersion: 1.3.1\n10/2023 \n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "illumipy is a Python module for estimating outside Illumination levels for given location, date and time.",
"version": "1.4.26",
"project_urls": {
"Homepage": "https://github.com/duckwilliam/illumipy",
"Repository": "https://github.com/duckwilliam/illumipy"
},
"split_keywords": [
"solar",
"illumination",
"sun",
"sunrise",
"sunset",
"sunlight",
"sunrise-sunset",
"openweathermap",
"brightness",
"light"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "700f9a32ac7ec2597924d5f6ac04ce8f0f9a40622e1ed674174c92ed9e25d2a8",
"md5": "b37b02a9500177cbb2e07f7626141840",
"sha256": "f97838ecac026ea92c980dbbdb4d376b6fd15d56f71bf1d40fe60543d52c191d"
},
"downloads": -1,
"filename": "illumipy-1.4.26-py3-none-any.whl",
"has_sig": false,
"md5_digest": "b37b02a9500177cbb2e07f7626141840",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11,<4.0",
"size": 15762,
"upload_time": "2023-10-31T10:08:44",
"upload_time_iso_8601": "2023-10-31T10:08:44.742368Z",
"url": "https://files.pythonhosted.org/packages/70/0f/9a32ac7ec2597924d5f6ac04ce8f0f9a40622e1ed674174c92ed9e25d2a8/illumipy-1.4.26-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "50f674ca7df0dd972a2f31338174d76fb5a9ae119b3e712f0be45e954b41d01c",
"md5": "be0501c21e2cbfda6e7bdccb86914df2",
"sha256": "496b2fa5d6f6f75ac2291b51f7f450b8f192e8504702cd4e03df070a2cbfc10b"
},
"downloads": -1,
"filename": "illumipy-1.4.26.tar.gz",
"has_sig": false,
"md5_digest": "be0501c21e2cbfda6e7bdccb86914df2",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11,<4.0",
"size": 26874,
"upload_time": "2023-10-31T10:08:46",
"upload_time_iso_8601": "2023-10-31T10:08:46.641054Z",
"url": "https://files.pythonhosted.org/packages/50/f6/74ca7df0dd972a2f31338174d76fb5a9ae119b3e712f0be45e954b41d01c/illumipy-1.4.26.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-10-31 10:08:46",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "duckwilliam",
"github_project": "illumipy",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "illumipy"
}
JSON
