initial commit

.github/workflows/CompatHelper.yml

@@ -0,0 +1,16 @@
+name: CompatHelper
+on:
+  schedule:
+    - cron: '00 00 * * *'
+  workflow_dispatch:
+jobs:
+  CompatHelper:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Pkg.add("CompatHelper")
+        run: julia -e 'using Pkg; Pkg.add("CompatHelper")'
+      - name: CompatHelper.main()
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          COMPATHELPER_PRIV: ${{ secrets.COMPATHELPER_PRIV }}  # optional
+        run: julia -e 'using CompatHelper; CompatHelper.main()'

.github/workflows/Documentation.yml

@@ -0,0 +1,24 @@
+name: Documentation
+
+on:
+  push:
+    branches:
+      - master
+    tags: '*'
+  pull_request:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - uses: julia-actions/setup-julia@latest
+        with:
+          version: '1.5'
+      - name: Install dependencies
+        run: julia --project=docs/ -e 'using Pkg; Pkg.develop(PackageSpec(path=pwd())); Pkg.instantiate()'
+      - name: Build and deploy
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} # For authentication with GitHub Actions token
+          DOCUMENTER_KEY: ${{ secrets.DOCUMENTER_KEY }} # For authentication with SSH deploy key
+        run: julia --project=docs/ docs/make.jl

.github/workflows/TagBot.yml

@@ -0,0 +1,12 @@
+name: TagBot
+on:
+  schedule:
+    - cron: 0 * * * *
+jobs:
+  TagBot:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: JuliaRegistries/TagBot@v1
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+          ssh: ${{ secrets.DOCUMENTER_KEY }}

.gitignore

@@ -0,0 +1,2 @@
+Manifest.toml
+docs/build

CONTRIBUTING.md

@@ -0,0 +1,29 @@
+# AzStorage.jl contributor guidelines
+
+## Issue reporting
+If you have found a bug in AzStorage.jl or have any suggestions for changes to
+AzStorage.jl functionality, please consider filing an issue using the GitHub
+isssue tracker.  Please do not forget to search for an existing issue
+which may already cover your suggestion.
+
+## Contributing
+We try to follow GitHub flow (https://guides.github.com/introduction/flow/) for
+making changes to AzStorage.jl.  Contributors retain copyright on their
+contributions, and the MIT license (https://opensource.org/licenses/MIT)
+applies to the contribution.
+
+The basic steps to making a contribution are as follows, and assume some knowledge of
+git:
+  1. fork the AzStorage.jl repository
+  2. create an appropriately titled branch for your contribution
+  3. if applicable, add a unit-test to ensure the functionality of your contribution
+  (see the `test` subfolder).
+  4. run `]test AzStorage` in the `test` folder
+  5. make a pull-request
+  6. have fun
+
+## Coding conventions
+We try to follow the same coding conventions as https://github.com/JuliaLang/julia.
+This primarily means using 4 spaces to indent (no tabs).  In addition, we make a
+best attempt to follow the guidelines in the style guide chapter of the julia
+manual: https://docs.julialang.org/en/v1/manual/style-guide/

LICENSE.md

@@ -0,0 +1,22 @@
+The AzStorage.jl package is licensed under the MIT "Expat" License:
+
+> Copyright (c) 2020: Chevron U.S.A. Inc.
+>
+> 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.

Project.toml

@@ -0,0 +1,29 @@
+name = "AzStorage"
+uuid = "c6697862-1611-5eae-9ef8-48803c85c8d6"
+version = "0.17.0"
+
+[deps]
+AbstractStorage = "14dbef02-f468-5f15-853e-5ec8dee7b899"
+AzSessions = "f239b30d-ae6b-58be-a2d5-7e9f30e280a9"
+AzStorage_jll = "00c928b4-b5f3-54d8-b38d-afd4635c4ad2"
+Base64 = "2a0f44e3-6c83-55bd-87e4-b1978d98bd5f"
+HTTP = "cd3eb016-35fb-5094-929b-558a96fad6f3"
+LightXML = "9c8b4983-aa76-5018-a973-4c85ecc9e179"
+Serialization = "9e88b42a-f829-5b0c-bbe9-9e923198166b"
+Sockets = "6462fe0b-24de-5631-8697-dd941f90decc"
+
+[compat]
+julia = "1"
+AbstractStorage = "1"
+AzSessions = "1"
+HTTP = "0.8"
+LightXML = "0.9"
+
+[extras]
+Dates = "ade2ca70-3891-5945-98fb-dc099432e06a"
+JSON = "682c06a0-de6a-54ab-a142-c8b1cf79cde6"
+Random = "9a3f8284-a2c9-5f02-9a11-845980a1fd5c"
+Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
+
+[targets]
+test = ["Dates", "JSON", "Random", "Test"]

README.md

@@ -0,0 +1,18 @@
+# AzStorage
+Interface to Azure blob storage.
+
+```julia
+using AzSessions, AzStorage
+
+mysession = AzCCSession(client_id="myclientid", client_secret="myclientsecret", resource="https://storage.azure.com")
+container = AzContainer("foo", storageaccount="myaccount", session=mysession)
+
+mkpath(container)
+write(container, "blob", rand(10))
+
+readdir(container)
+
+x = read!(container, "blob", Vector{Float64}(undef, 10))
+
+...
+```

docs/make.jl

@@ -0,0 +1,3 @@
+using Documenter, AzStorage
+
+makedocs(sitename="AzStorage", modules=[AzStorage])

docs/src/example.md

@@ -0,0 +1,53 @@
+# Example
+
+Here we show basic usage where we 1) create a container, 2) write a blob to the container, 3) list the contents of the container, 4) read the blob that was previously created, and 5) delete the container and its contents.
+
+```julia
+using Pkg
+Pkg.add("AzSessions")
+Pkg.add("AzStorage")
+
+using AzSessions, AzStorage
+
+# here we use client credentials, but auth-code-flow and device-code flow (etc.) are also available.
+# see the AzSessions.jl package for more details on authentication in Azure.
+session = AzSession(;protocal=AzClientCredentials, client_id="myclientid", client_secret="verysecret", resource="https://storage.azure.com/")
+
+# create a handle to an Azure container in an existing storage account
+container = AzContainer("foo"; storageaccount="mystorageaccount", session=session)
+
+# create the container
+mkpath(container)
+
+# write a blob to the container
+write(container, "myblob.bin", rand(10))
+
+# list the blobs in the container
+readdir(container)
+
+# read the contents of the blob
+x = read!(container, "myblob.bin", Vector{Float64}(undef, 10))
+
+# remove the container, and its contents
+rm(x)
+```
+
+In addition, we can represent blob's, providing an API that is similar to handling POSIX files.
+
+```julia
+# create a handle to a blob in a container
+io = open(AzContainer("foo"; storageaccount="mystorageaccount"), "myblob.bin")
+io = joinpath(AzContainer("foo"; storageaccount="mystorageaccount"), "myblob.bin") # this is equivalent to the previous line.
+
+# write to the blob
+write(io, rand(10))
+
+# read the blob
+x = read!(io, zeros(10))
+
+# check that the blob exists
+isfile(x)
+
+# remove the blob
+rm(x)
+```

docs/src/index.md

@@ -0,0 +1,4 @@
+# AzStorage
+AzStorage is a Julia API for Azure storage.  AzStorage provides methods for interacting
+with Azure containers and blobs.  In order to obtain reasonable through-put, I/O is threaded via
+OpenMP.  In the case of writing, Azure block-blobs are used to help organize the threaded I/O.

docs/src/reference.md

@@ -0,0 +1,30 @@
+# Reference
+
+## Construct an Azure Container
+```@docs
+AzContainer
+```
+
+## Container methods
+```@docs
+containers
+cp
+dirname
+isdir
+mkpath
+readdir
+rm(::AzContainer)
+```
+
+## Blob methods
+```@docs
+filesize
+isfile
+joinpath
+open
+read
+read!
+rm(::AzContainer, ::AbstractString)
+rm(::AzStorage.AzObject)
+write
+```