path: root/python-arlulaapi.spec

%global _empty_manifest_terminate_build 0
Name:		python-arlulaapi
Version:	1.4.0
Release:	1
Summary:	A package to facilitate access to the Arlula Imagery Marketplace API
License:	MIT License
URL:		https://github.com/Arlula/python-archive-sdk.git
Source0:	https://mirrors.nju.edu.cn/pypi/web/packages/95/74/515e136067d529e0402ff5db0718b77a476b65bffaf5f95aa69de3f2af63/arlulaapi-1.4.0.tar.gz
BuildArch:	noarch

Requires:	python3-grequests
Requires:	python3-requests
Requires:	python3-pgeocode
Requires:	python3-arlulacore

%description
# **Arlula API Python Package**
## About
The Arlula API allows users to query databases of satellite imagery from vendors around the world. This powerful tool allows users to search and compare the quality of global image datasets and order them at scale. The Arlula API is a new way in which people from around the world can access timely satellite imagery and create their own data streams from space!  
The Arlula Python package makes it easy to access all of the API functionality without having to do any of the hard work.  
A more verbose tutorial can be found at https://arlula.com/using-your-arlula-api-key-python/.

## Prerequisites
This package requires an active Arlula account and access to the API credentials. If you don't have an account, you can create one at [api.arlula.com/signup](https://api.arlula.com/signup).

## Installation
```bash
pip install arlulaapi
```
## Initiation
Instantiate an ArlulaSession object using your API credentials as below. This will validate your credentials and store them for the remainder of the session.
```python
import arlulaapi

"""opening a session"""
arlula_session = arlulaapi.ArlulaSession(key, secret)
# Call required methods

"""using a context manager"""
with arlulaapi.ArlulaSession(key, secret) as arlula_session :
    # Call required methods
```

## Utilities
A maximum cloud filter can be set on search results. If unset, it defaults to 100%.
```python
# Only return images with <40% cloud
arlula_session.set_max_cloud(40)
```

## API Endpoints
This package contains methods for each of the supported API endpoints. Each method returns an object as prescribed in the Arlula API documentation. The available parameters and an example of each method is below:
### Search
```python
# Available parameters:
search_result = arlula_session.search(
    start="string",
    end="string"
    res="string",
    lat=float,
    long=float,
    north=float,
    south=float,
    east=float,
    west=float
)

search_result = arlula_session.search(
    start="2014-01-01",
    res="vlow",
    lat=40.84,
    long=60.15
)
```
### Order
```python
order = arlula_session.order(
    id=orderId,
    eula="",
    seats=1,
    webhooks=[...],
    emails=[...]
)
```
### Get resource
```python
## Downloads the resource to the specified filepath
# Optional suppress parameter controls console output
arlula_session.get_resource(
    id=resourceId,
    filepath="downloads/thumbnail.jpg",
    # optional
    suppress="false"
)
```
### Get order(s)
```python
order = arlula_session.get_order(
    id="orderId"
)

orders = arlula_session.list_orders()
```
## Other methods _(experimental)_
As well as supporting all of the Arlula API endpoints, this package provides other mechanisms of utilising the API.

**Group search**

The ArlulaSession `gsearch` method allows you to perform multiple searches at once, and have the results collated into a large search result object. To use the group search method, pass a list of _GroupSearch_ objects, as below. The parameters for each search must pass the same requirements as the `search` method.
```python
group_search = [
    {
        "start":"2014-01-01",
        "res":"vlow",
        "lat":40.84,
        "long":60.15
    },
    {
        "start":"2014-01-01",
        "end":"2014-02-01",
        "res":"vlow",
        "lat":30,
        "long":30   
    },
    {
        "start":"2015-01-03",
        "end":"2015-03-03",
        "res":"vlow",
        "south":-29.5,
        "north":30.5,
        "east":30.5,
        "west":-29.5
    }
]
search_result=arlula_session.gsearch(group_search) # A list of search result objects
```
**Order download**

The Arlula API also provides the option to download an entire order's resources into a specified folder, as below. You may also pass an optional `suppress` parameter to remove all console output.
```python
arlula_session.get_order_resources(
    id=orderId,
    folder="downloads/ordersample",
    suppress=True
)
```
**Search by postcode**

The ArlulaSession `search_postcode` method utilises the [pgeocode](https://pypi.org/project/pgeocode/) API to search by postcode. The method requires a country's [two-letter ISO code](https://www.iban.com/country-codes), and can take either a single postcode or a list of postcodes. The returned object will contain a `location` object, with `postcode`, `lat`, `long` and `name`, and a `data` object, which contains either the search result or the gsearch result (depending on if more than 1 postcode is passed into the function).
An optional `boxsize` parameter may be passed in to create a bounding box around each location - this box is a square, with each edge `boxsize` kms from the postcode's centroid.
```python
# Searches a 10x10km square centred on Paris
res = arlula_session.search_postcode(
    start="2019-01-01",
    res="vlow",
    country="fr",
    postcode="75013",
    boxsize=5
)
print(res.location.name) # prints "Paris"
search_result = res.data

# Searches each of Australia's capital cities
res = arlula_session.search_postcode(
    start="2019-01-01",
    end="2019-03-01",
    res="med",
    country="au",
    postcode=["2000", "2600", "3000", "4000", "5000", "6000", "7000", "0800"],
)
print(res[2].location.name) # prints "Melbourne"
search_result = res[2].data # Melbourne search result
```

## Advanced
**Allow async features**

Async features can be turned on at instantiation for better performance in gsearch.
```python
arlula_session = arlulaapi.ArlulaSession(key, secret, allow_async=True)
```
Note that it is up to the user to monkey-patch with the gevent package, i.e. including the following code at the very top of their python file:
```python
from gevent import monkey as curious_george
curious_george.patch_all(thread=False, select=False)
```



%package -n python3-arlulaapi
Summary:	A package to facilitate access to the Arlula Imagery Marketplace API
Provides:	python-arlulaapi
BuildRequires:	python3-devel
BuildRequires:	python3-setuptools
BuildRequires:	python3-pip
%description -n python3-arlulaapi
# **Arlula API Python Package**
## About
The Arlula API allows users to query databases of satellite imagery from vendors around the world. This powerful tool allows users to search and compare the quality of global image datasets and order them at scale. The Arlula API is a new way in which people from around the world can access timely satellite imagery and create their own data streams from space!  
The Arlula Python package makes it easy to access all of the API functionality without having to do any of the hard work.  
A more verbose tutorial can be found at https://arlula.com/using-your-arlula-api-key-python/.

## Prerequisites
This package requires an active Arlula account and access to the API credentials. If you don't have an account, you can create one at [api.arlula.com/signup](https://api.arlula.com/signup).

## Installation
```bash
pip install arlulaapi
```
## Initiation
Instantiate an ArlulaSession object using your API credentials as below. This will validate your credentials and store them for the remainder of the session.
```python
import arlulaapi

"""opening a session"""
arlula_session = arlulaapi.ArlulaSession(key, secret)
# Call required methods

"""using a context manager"""
with arlulaapi.ArlulaSession(key, secret) as arlula_session :
    # Call required methods
```

## Utilities
A maximum cloud filter can be set on search results. If unset, it defaults to 100%.
```python
# Only return images with <40% cloud
arlula_session.set_max_cloud(40)
```

## API Endpoints
This package contains methods for each of the supported API endpoints. Each method returns an object as prescribed in the Arlula API documentation. The available parameters and an example of each method is below:
### Search
```python
# Available parameters:
search_result = arlula_session.search(
    start="string",
    end="string"
    res="string",
    lat=float,
    long=float,
    north=float,
    south=float,
    east=float,
    west=float
)

search_result = arlula_session.search(
    start="2014-01-01",
    res="vlow",
    lat=40.84,
    long=60.15
)
```
### Order
```python
order = arlula_session.order(
    id=orderId,
    eula="",
    seats=1,
    webhooks=[...],
    emails=[...]
)
```
### Get resource
```python
## Downloads the resource to the specified filepath
# Optional suppress parameter controls console output
arlula_session.get_resource(
    id=resourceId,
    filepath="downloads/thumbnail.jpg",
    # optional
    suppress="false"
)
```
### Get order(s)
```python
order = arlula_session.get_order(
    id="orderId"
)

orders = arlula_session.list_orders()
```
## Other methods _(experimental)_
As well as supporting all of the Arlula API endpoints, this package provides other mechanisms of utilising the API.

**Group search**

The ArlulaSession `gsearch` method allows you to perform multiple searches at once, and have the results collated into a large search result object. To use the group search method, pass a list of _GroupSearch_ objects, as below. The parameters for each search must pass the same requirements as the `search` method.
```python
group_search = [
    {
        "start":"2014-01-01",
        "res":"vlow",
        "lat":40.84,
        "long":60.15
    },
    {
        "start":"2014-01-01",
        "end":"2014-02-01",
        "res":"vlow",
        "lat":30,
        "long":30   
    },
    {
        "start":"2015-01-03",
        "end":"2015-03-03",
        "res":"vlow",
        "south":-29.5,
        "north":30.5,
        "east":30.5,
        "west":-29.5
    }
]
search_result=arlula_session.gsearch(group_search) # A list of search result objects
```
**Order download**

The Arlula API also provides the option to download an entire order's resources into a specified folder, as below. You may also pass an optional `suppress` parameter to remove all console output.
```python
arlula_session.get_order_resources(
    id=orderId,
    folder="downloads/ordersample",
    suppress=True
)
```
**Search by postcode**

The ArlulaSession `search_postcode` method utilises the [pgeocode](https://pypi.org/project/pgeocode/) API to search by postcode. The method requires a country's [two-letter ISO code](https://www.iban.com/country-codes), and can take either a single postcode or a list of postcodes. The returned object will contain a `location` object, with `postcode`, `lat`, `long` and `name`, and a `data` object, which contains either the search result or the gsearch result (depending on if more than 1 postcode is passed into the function).
An optional `boxsize` parameter may be passed in to create a bounding box around each location - this box is a square, with each edge `boxsize` kms from the postcode's centroid.
```python
# Searches a 10x10km square centred on Paris
res = arlula_session.search_postcode(
    start="2019-01-01",
    res="vlow",
    country="fr",
    postcode="75013",
    boxsize=5
)
print(res.location.name) # prints "Paris"
search_result = res.data

# Searches each of Australia's capital cities
res = arlula_session.search_postcode(
    start="2019-01-01",
    end="2019-03-01",
    res="med",
    country="au",
    postcode=["2000", "2600", "3000", "4000", "5000", "6000", "7000", "0800"],
)
print(res[2].location.name) # prints "Melbourne"
search_result = res[2].data # Melbourne search result
```

## Advanced
**Allow async features**

Async features can be turned on at instantiation for better performance in gsearch.
```python
arlula_session = arlulaapi.ArlulaSession(key, secret, allow_async=True)
```
Note that it is up to the user to monkey-patch with the gevent package, i.e. including the following code at the very top of their python file:
```python
from gevent import monkey as curious_george
curious_george.patch_all(thread=False, select=False)
```



%package help
Summary:	Development documents and examples for arlulaapi
Provides:	python3-arlulaapi-doc
%description help
# **Arlula API Python Package**
## About
The Arlula API allows users to query databases of satellite imagery from vendors around the world. This powerful tool allows users to search and compare the quality of global image datasets and order them at scale. The Arlula API is a new way in which people from around the world can access timely satellite imagery and create their own data streams from space!  
The Arlula Python package makes it easy to access all of the API functionality without having to do any of the hard work.  
A more verbose tutorial can be found at https://arlula.com/using-your-arlula-api-key-python/.

## Prerequisites
This package requires an active Arlula account and access to the API credentials. If you don't have an account, you can create one at [api.arlula.com/signup](https://api.arlula.com/signup).

## Installation
```bash
pip install arlulaapi
```
## Initiation
Instantiate an ArlulaSession object using your API credentials as below. This will validate your credentials and store them for the remainder of the session.
```python
import arlulaapi

"""opening a session"""
arlula_session = arlulaapi.ArlulaSession(key, secret)
# Call required methods

"""using a context manager"""
with arlulaapi.ArlulaSession(key, secret) as arlula_session :
    # Call required methods
```

## Utilities
A maximum cloud filter can be set on search results. If unset, it defaults to 100%.
```python
# Only return images with <40% cloud
arlula_session.set_max_cloud(40)
```

## API Endpoints
This package contains methods for each of the supported API endpoints. Each method returns an object as prescribed in the Arlula API documentation. The available parameters and an example of each method is below:
### Search
```python
# Available parameters:
search_result = arlula_session.search(
    start="string",
    end="string"
    res="string",
    lat=float,
    long=float,
    north=float,
    south=float,
    east=float,
    west=float
)

search_result = arlula_session.search(
    start="2014-01-01",
    res="vlow",
    lat=40.84,
    long=60.15
)
```
### Order
```python
order = arlula_session.order(
    id=orderId,
    eula="",
    seats=1,
    webhooks=[...],
    emails=[...]
)
```
### Get resource
```python
## Downloads the resource to the specified filepath
# Optional suppress parameter controls console output
arlula_session.get_resource(
    id=resourceId,
    filepath="downloads/thumbnail.jpg",
    # optional
    suppress="false"
)
```
### Get order(s)
```python
order = arlula_session.get_order(
    id="orderId"
)

orders = arlula_session.list_orders()
```
## Other methods _(experimental)_
As well as supporting all of the Arlula API endpoints, this package provides other mechanisms of utilising the API.

**Group search**

The ArlulaSession `gsearch` method allows you to perform multiple searches at once, and have the results collated into a large search result object. To use the group search method, pass a list of _GroupSearch_ objects, as below. The parameters for each search must pass the same requirements as the `search` method.
```python
group_search = [
    {
        "start":"2014-01-01",
        "res":"vlow",
        "lat":40.84,
        "long":60.15
    },
    {
        "start":"2014-01-01",
        "end":"2014-02-01",
        "res":"vlow",
        "lat":30,
        "long":30   
    },
    {
        "start":"2015-01-03",
        "end":"2015-03-03",
        "res":"vlow",
        "south":-29.5,
        "north":30.5,
        "east":30.5,
        "west":-29.5
    }
]
search_result=arlula_session.gsearch(group_search) # A list of search result objects
```
**Order download**

The Arlula API also provides the option to download an entire order's resources into a specified folder, as below. You may also pass an optional `suppress` parameter to remove all console output.
```python
arlula_session.get_order_resources(
    id=orderId,
    folder="downloads/ordersample",
    suppress=True
)
```
**Search by postcode**

The ArlulaSession `search_postcode` method utilises the [pgeocode](https://pypi.org/project/pgeocode/) API to search by postcode. The method requires a country's [two-letter ISO code](https://www.iban.com/country-codes), and can take either a single postcode or a list of postcodes. The returned object will contain a `location` object, with `postcode`, `lat`, `long` and `name`, and a `data` object, which contains either the search result or the gsearch result (depending on if more than 1 postcode is passed into the function).
An optional `boxsize` parameter may be passed in to create a bounding box around each location - this box is a square, with each edge `boxsize` kms from the postcode's centroid.
```python
# Searches a 10x10km square centred on Paris
res = arlula_session.search_postcode(
    start="2019-01-01",
    res="vlow",
    country="fr",
    postcode="75013",
    boxsize=5
)
print(res.location.name) # prints "Paris"
search_result = res.data

# Searches each of Australia's capital cities
res = arlula_session.search_postcode(
    start="2019-01-01",
    end="2019-03-01",
    res="med",
    country="au",
    postcode=["2000", "2600", "3000", "4000", "5000", "6000", "7000", "0800"],
)
print(res[2].location.name) # prints "Melbourne"
search_result = res[2].data # Melbourne search result
```

## Advanced
**Allow async features**

Async features can be turned on at instantiation for better performance in gsearch.
```python
arlula_session = arlulaapi.ArlulaSession(key, secret, allow_async=True)
```
Note that it is up to the user to monkey-patch with the gevent package, i.e. including the following code at the very top of their python file:
```python
from gevent import monkey as curious_george
curious_george.patch_all(thread=False, select=False)
```



%prep
%autosetup -n arlulaapi-1.4.0

%build
%py3_build

%install
%py3_install
install -d -m755 %{buildroot}/%{_pkgdocdir}
if [ -d doc ]; then cp -arf doc %{buildroot}/%{_pkgdocdir}; fi
if [ -d docs ]; then cp -arf docs %{buildroot}/%{_pkgdocdir}; fi
if [ -d example ]; then cp -arf example %{buildroot}/%{_pkgdocdir}; fi
if [ -d examples ]; then cp -arf examples %{buildroot}/%{_pkgdocdir}; fi
pushd %{buildroot}
if [ -d usr/lib ]; then
	find usr/lib -type f -printf "/%h/%f\n" >> filelist.lst
fi
if [ -d usr/lib64 ]; then
	find usr/lib64 -type f -printf "/%h/%f\n" >> filelist.lst
fi
if [ -d usr/bin ]; then
	find usr/bin -type f -printf "/%h/%f\n" >> filelist.lst
fi
if [ -d usr/sbin ]; then
	find usr/sbin -type f -printf "/%h/%f\n" >> filelist.lst
fi
touch doclist.lst
if [ -d usr/share/man ]; then
	find usr/share/man -type f -printf "/%h/%f.gz\n" >> doclist.lst
fi
popd
mv %{buildroot}/filelist.lst .
mv %{buildroot}/doclist.lst .

%files -n python3-arlulaapi -f filelist.lst
%dir %{python3_sitelib}/*

%files help -f doclist.lst
%{_docdir}/*

%changelog
* Tue May 30 2023 Python_Bot <Python_Bot@openeuler.org> - 1.4.0-1
- Package Spec generated