Skip to content

Commit

Permalink
Merge branch 'release/0.1.0'
Browse files Browse the repository at this point in the history
  • Loading branch information
Wing Chau committed Nov 27, 2019
2 parents d1ae742 + 2854123 commit 1d9c5a5
Show file tree
Hide file tree
Showing 36 changed files with 1,708 additions and 69 deletions.
7 changes: 4 additions & 3 deletions .devcontainer/devcontainer.json
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
// For format details, see https://aka.ms/vscode-remote/devcontainer.json or the definition README at
// https://github.com/microsoft/vscode-dev-containers/tree/master/containers/docker-existing-dockerfile
{
"name": "Market Data Fetchers",
"name": "Alpha Vantage",

// Sets the run context to one level up instead of the .devcontainer folder.
"context": "..",
Expand Down Expand Up @@ -40,11 +40,12 @@
// "appPort": [],

// Uncomment the next line to run commands after the container is created - for example installing git.
"postCreateCommand": "apt update && apt upgrade -y && apt install -y git-flow vim",
"postCreateCommand": "apt update && apt upgrade -y && apt install -y git-flow vim && cd /root && git clone https://github.com/nicklockwood/SwiftFormat && cd SwiftFormat && swift build -c release && mv .build/x86_64-unknown-linux/release/swiftformat /usr/local/bin/",

// Add the IDs of extensions you want installed when the container is created in the array below.
"extensions": [
"vadimcn.vscode-lldb",
"vknabel.vscode-swift-development-environment"
"vknabel.vscode-swift-development-environment",
"vknabel.vscode-swiftformat"
]
}
4 changes: 4 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
@@ -1,5 +1,9 @@
.DS_Store
/.vscode
/.build
/.swiftpm
/Packages
/*.xcodeproj
xcuserdata/

/Tests/AlphaVantageTests/PrivateConst.swift
23 changes: 23 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,23 @@
# Changelog
All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog], and this project adheres to
[Semantic Versioning].

## [Unreleased]

## [0.1.0] - 2019-11-27

### Added
- Swift library module `AlphaVantage`:
- Partial implementation of `Stock Time Series` functions including
`TIME_SERIES_INTRADAY`, `TIME_SERIES_DAILY`, and
`TIME_SERIES_DAILY_ADJUSTED`.
- Command line executable:
- Basic command line interface.
- Command `sav stock <intraday/daily/daily-adjusted> <symbol> [options]`

[Keep a Changelog]: https://keepachangelog.com/en/1.0.0/
[Semantic Versioning]: https://semver.org/spec/v2.0.0.html
[Unreleased]: https://github.com/iamWing/swift-alpha-vantage/compare/0.1.0...HEAD
[0.1.0]: https://github.com/iamWing/swift-alpha-vantage/releases/tag/0.1.0
21 changes: 21 additions & 0 deletions LICENSE
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
MIT License

Copyright (c) 2019 Devtography

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
97 changes: 97 additions & 0 deletions Package.resolved
Original file line number Diff line number Diff line change
@@ -0,0 +1,97 @@
{
"object": {
"pins": [
{
"package": "async-http-client",
"repositoryURL": "https://github.com/swift-server/async-http-client.git",
"state": {
"branch": null,
"revision": "d84a1da59e0fa879cde27e01cdf9f079208cc0cc",
"version": "1.0.0-alpha.4"
}
},
{
"package": "CircuitBreaker",
"repositoryURL": "https://github.com/IBM-Swift/CircuitBreaker.git",
"state": {
"branch": null,
"revision": "e9345aa721ca4da428777f2e953b9ad534017675",
"version": "5.0.3"
}
},
{
"package": "Configuration",
"repositoryURL": "https://github.com/IBM-Swift/Configuration.git",
"state": {
"branch": null,
"revision": "da98da148509a3d7bd61fe01e7ade8926b52026b",
"version": "3.0.4"
}
},
{
"package": "FileKit",
"repositoryURL": "https://github.com/IBM-Swift/FileKit.git",
"state": {
"branch": null,
"revision": "26911acde61a3556b7583f84180048ea6a03973c",
"version": "0.0.2"
}
},
{
"package": "LoggerAPI",
"repositoryURL": "https://github.com/IBM-Swift/LoggerAPI.git",
"state": {
"branch": null,
"revision": "3357dd9526cdf9436fa63bb792b669e6efdc43da",
"version": "1.9.0"
}
},
{
"package": "swift-log",
"repositoryURL": "https://github.com/apple/swift-log.git",
"state": {
"branch": null,
"revision": "e8aabbe95db22e064ad42f1a4a9f8982664c70ed",
"version": "1.1.1"
}
},
{
"package": "swift-nio",
"repositoryURL": "https://github.com/apple/swift-nio.git",
"state": {
"branch": null,
"revision": "8066b0f581604e3711979307a4377457e2b0f007",
"version": "2.9.0"
}
},
{
"package": "swift-nio-ssl",
"repositoryURL": "https://github.com/apple/swift-nio-ssl.git",
"state": {
"branch": null,
"revision": "e5c1af45ac934ac0a6117b2927a51d845cf4f705",
"version": "2.4.3"
}
},
{
"package": "SwiftCLI",
"repositoryURL": "https://github.com/jakeheis/SwiftCLI",
"state": {
"branch": null,
"revision": "df4d5b3ec2c1421a58d71010ff43528db5b19e04",
"version": "5.3.3"
}
},
{
"package": "SwiftyRequest",
"repositoryURL": "https://github.com/IBM-Swift/SwiftyRequest",
"state": {
"branch": null,
"revision": "6b12cda627f5a6f03b5ccf654554cb9482d870be",
"version": "3.0.0"
}
}
]
},
"version": 1
}
31 changes: 26 additions & 5 deletions Package.swift
Original file line number Diff line number Diff line change
Expand Up @@ -4,19 +4,40 @@
import PackageDescription

let package = Package(
name: "MarketDataFetchers",
name: "Swift Alpha Vantage",
products: [
.executable(name: "AlphaVantageExecutable",
targets: ["AlphaVantageExecutable"]),
.library(name: "AlphaVantage", targets: ["AlphaVantage"])
],
dependencies: [
// Dependencies declare other packages that this package depends on.
// .package(url: /* package url */, from: "1.0.0"),
.package(
url: "https://github.com/jakeheis/SwiftCLI",
from: "5.3.3"
),
.package(
url: "https://github.com/IBM-Swift/Configuration.git",
from: "3.0.4"
),
.package(url: "https://github.com/IBM-Swift/SwiftyRequest",
from: "3.0.0"),
],
targets: [
// Targets are the basic building blocks of a package. A target can define a module or a test suite.
// Targets can depend on other targets in this package, and on products in packages which this package depends on.
.target(
name: "MarketDataFetchers",
dependencies: []),
name: "AlphaVantageExecutable",
dependencies: ["AlphaVantage", "Configuration", "SwiftCLI"]
),
.target(
name: "AlphaVantage",
dependencies: ["SwiftyRequest"]
),
.testTarget(
name: "MarketDataFetchersTests",
dependencies: ["MarketDataFetchers"]),
name: "AlphaVantageTests",
dependencies: ["AlphaVantage", "SwiftyRequest"]
),
]
)
143 changes: 141 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,3 +1,142 @@
# MarketDataFetchers
# swift-alpha-vantage

A description of this package.
_Swift package to get market data from Alpha Vantage APIs_

[Alpha Vantage] provides a set of free APIs for realtime and historical data on
stocks, forex (FX), and digital/crypto currencies. This package implements a
command line script and a Swift module to the free APIs provided by Alpha
Vantage.

This package requires a free API key from Alpha Vantage in order to fetch
market data there. The API key can be requested on
http://www.alphavantage.co/support/#api-key

## Getting Started

#### _Before you get started_

_This package is written and tested on macOS & Ubuntu, whereas iOS has not been
tested and not guaranteed to work. You are welcome to give it a try and post an
issue to let me know if it works or not, thanks._

### Using as dependency via Swift Package Manager

#### Add dependencies

Add `swift-alpha-vantage` to the dependencies within your application's
`Package.swift` file. Substitute `"x.x.x" with the latest `swift-alpha-vantage`
[release].

```Swift
.package(url: "https://github.com/iamWing/swift-alpha-vantage", from: "x.x.x")
```

Add `AlphaVantage` to your target's dependencies:
```Swift
.target(name: "example", dependencies: ["AlphaVantage"])
```

#### Initialise AlphaVantage

```Swift
import Foundation
import AlphaVantage

let fetcher = Stock(
apiKey: "alpha_vantage_api_key",
export: (path: URL(fileURLWithPath: "."), dataType: .json)
)
```

#### Fetching market data

```Swift
fetcher.fetchStockIntraday(symbol: "MSFT", interval: .min15) { result, err in
if let err = err {
guard let apiErr = err as? ApiResponse.ApiError else {
self.stderr <<< err.localizedDescription
return
}

self.stderr <<< apiErr.errMsg
}
}
```

### Command line executable

#### Download Swift Alpha Vantage

```sh
# Substitute "x.x.x" with the latest release
curl https://github.com/iamWing/swift-alpha-vantage/releases/download/x.x.x/sav -o sav
```

#### Configure API Key

The Alpha Vantage API key can be configured via either environment variable
`API_KEY` or a separate `config.json` file alongside the executable file `sav`.

_If both environment variable `API_KEY` and `config.json` file are both
configured, the api key declared in environment variable will be used for the
convenience of quick api key modification._

```sh
# By environment variable
export API_KEY=your_api_key
```

```sh
# config.json
{
"API_KEY": "your_api_key"
}
```

#### Usage

```sh
sav stock <function> <symbol> [options]

# e.g.
sav stock intraday -i 5 -o /home/ MSFT

# Available API functions:
# intraday, daily, daily-adjusted
```

## Remarks

The development of this package is still in early days, therefore only a few
API functions provided by Alpha Vantage are implemented atm. Given the limited
amount of free time I have recently, the progress on the remaining functions is
likely to be slow in the foreseeable future. You're more than welcome to
participate the development if you've got the time.

## Contributions

Contributions via pull requests are welcome and encouraged :)

In order to run the unit tests, you'll need to create a file
`PrivateConst.swift` under the folder `Tests/AlphaVantageTests/` for storing
the API key for unit tests, otherwise the test module won't be able to compile.

```Swift
// PrivateConst.swift
enum PrivateConst {
static var apiKey: String { return "your-api-key" }
}
```

## Author

[Wing Chau] [@Devtography]

## License

swift-alpha-vantage is licensed under the [MIT License](LICENSE).

[Alpha Vantage]: https://www.alphavantage.co
[release]: https://github.com/iamWing/swift-alpha-vantage/releases
[Wing Chau]: https://github.com/iamWing
[@Devtography]: https://github.com/Devtography
18 changes: 18 additions & 0 deletions Sources/AlphaVantage/APIs/AlphaVantage.swift
Original file line number Diff line number Diff line change
@@ -0,0 +1,18 @@
import Foundation

/// Protocol of Alpha Vantage API implementation classes.
public protocol AlphaVantage {
/// API key provided by Alpha Vantage.
var apiKey: String { get }
/// Optional. Data retrieved will be exported to file if set.
var export: (path: URL, dataType: ApiConst.DataType)? { get }

/**
Initialiser.

- parameters:
- apiKey: API key provided by Alpha Vantage.
- export: Declares to save the retrieved data as file in specified format & location or not.
*/
init(apiKey: String, export: (path: URL, dataType: ApiConst.DataType)?)
}
Loading

0 comments on commit 1d9c5a5

Please sign in to comment.