Throw exceptions instead of the ugly Result monad (#23)

.github/workflows/CI.yml

@@ -0,0 +1,45 @@
+name: CI
+on:
+  - push
+  - pull_request
+jobs:
+  test:
+    name: Julia ${{ matrix.version }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        version:
+          - '1.0'
+          - '1'
+          - 'nightly'
+    steps:
+      - uses: actions/checkout@v2
+      - uses: julia-actions/setup-julia@v1
+        with:
+          version: ${{ matrix.version }}
+      - uses: julia-actions/julia-buildpkg@v1
+      - uses: julia-actions/julia-runtest@v1
+        continue-on-error: ${{ matrix.version == 'nightly' }}
+  docs:
+    name: Documentation
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - uses: julia-actions/setup-julia@v1
+        with:
+          version: 1
+      - run: |
+          julia --project=docs -e '
+            using Pkg
+            Pkg.develop(PackageSpec(path=pwd()))
+            Pkg.instantiate()'
+      - run: |
+          julia --project=docs -e '
+            using Documenter: doctest
+            using GitForge
+            doctest(GitForge)'
+      - run: julia --project=docs docs/make.jl
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          DOCUMENTER_KEY: ${{ secrets.DOCUMENTER_KEY }}

LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2019 Chris de Graaf
+Copyright (c) 2019-2021 Chris de Graaf
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

Project.toml

@@ -1,7 +1,7 @@
 name = "GitForge"
 uuid = "8f6bce27-0656-5410-875b-07a5572985df"
-authors = ["Chris de Graaf <[email protected]>"]
-version = "0.1.7"
+authors = ["Chris de Graaf <[email protected]>"]
+version = "0.2.0"
 
 [deps]
 Dates = "ade2ca70-3891-5945-98fb-dc099432e06a"

README.md

@@ -1,7 +1,7 @@
 # GitForge
 
-[![Dev](https://img.shields.io/badge/docs-dev-blue.svg)](https://christopher-dg.github.io/GitForge.jl/dev)
-[![Build Status](https://travis-ci.com/github/JuliaWeb/GitForge.jl.svg?branch=master)](https://travis-ci.com/github/JuliaWeb/GitForge.jl)
+[![Dev](https://img.shields.io/badge/docs-dev-blue.svg)](https://juliaweb.github.io/GitForge.jl/dev)
+[![CI](https://github.com/JuliaWeb/GitForge.jl/actions/workflows/CI.yml/badge.svg)](https://github.com/JuliaWeb/GitForge.jl/actions/workflows/CI.yml)
 
 **GitForge.jl is a unified interface for interacting with Git ["forges"](https://en.wikipedia.org/wiki/Forge_(software)).**
 
@@ -10,19 +10,15 @@ julia> using GitForge, GitForge.GitHub
 
 julia> gh = GitHubAPI();
 
-julia> result = get_user(gh, "christopher-dG");
+julia> user, resp = get_user(gh, "christopher-dG");
 
-julia> isnothing(GitForge.exception(result))
-true
+julia> @assert resp.status == 200
 
-julia> GitForge.response(result).status
-200
-
-julia> GitForge.value(result).login
-"christopher-dG"
+julia> @assert user.login == "christopher-dG"
 ```
 
 ### API Coverage
 
 Eventually, the goal is to cover all the "basic" parts of services like GitHub, such as repositories, issues, pull requests, etc.
 However, this library was mostly motivated by development on [Registrator](https://github.com/JuliaRegistries/Registrator.jl), so at the moment most of the wrapped endpoints are just the ones needed for that specific task.
+More recently, it's being used for efforts on [CompatHelper](https://github.com/JuliaRegistries/CompatHelper.jl) and [TagBot](https://github.com/JuliaRegistries/TagBot).

docs/Manifest.toml

@@ -1,52 +1,105 @@
 # This file is machine-generated - editing it directly is not advised
 
+[[ArgTools]]
+uuid = "0dad84c5-d112-42e6-8d28-ef12dabb789f"
+
+[[Artifacts]]
+uuid = "56f22d72-fd6d-98f1-02f0-08ddc0907c33"
+
 [[Base64]]
 uuid = "2a0f44e3-6c83-55bd-87e4-b1978d98bd5f"
 
 [[Dates]]
 deps = ["Printf"]
 uuid = "ade2ca70-3891-5945-98fb-dc099432e06a"
 
-[[Distributed]]
-deps = ["Random", "Serialization", "Sockets"]
-uuid = "8ba89e20-285c-5b6f-9357-94700520ee1b"
-
 [[DocStringExtensions]]
 deps = ["LibGit2", "Markdown", "Pkg", "Test"]
-git-tree-sha1 = "4d30e889c9f106a51ffa4791a88ffd4765bf20c3"
+git-tree-sha1 = "9d4f64f79012636741cf01133158a54b24924c32"
 uuid = "ffbed154-4ef7-542d-bbb7-c09d3a79fcae"
-version = "0.7.0"
+version = "0.8.4"
 
 [[Documenter]]
-deps = ["Base64", "DocStringExtensions", "InteractiveUtils", "LibGit2", "Logging", "Markdown", "Pkg", "REPL", "Random", "Test", "Unicode"]
-git-tree-sha1 = "a8c41ba3d0861240dbec942ee1d0f86c57c37c1c"
+deps = ["Base64", "Dates", "DocStringExtensions", "IOCapture", "InteractiveUtils", "JSON", "LibGit2", "Logging", "Markdown", "REPL", "Test", "Unicode"]
+git-tree-sha1 = "3ebb967819b284dc1e3c0422229b58a40a255649"
 uuid = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
-version = "0.21.5"
+version = "0.26.3"
+
+[[Downloads]]
+deps = ["ArgTools", "LibCURL", "NetworkOptions"]
+uuid = "f43a241f-c20a-4ad4-852c-f6b1247861c6"
+
+[[IOCapture]]
+deps = ["Logging"]
+git-tree-sha1 = "377252859f740c217b936cebcd918a44f9b53b59"
+uuid = "b5f81e59-6552-4d32-b1f0-c071b021bf89"
+version = "0.1.1"
 
 [[InteractiveUtils]]
 deps = ["Markdown"]
 uuid = "b77e0a4c-d291-57a0-90e8-8db25a27a240"
 
+[[JSON]]
+deps = ["Dates", "Mmap", "Parsers", "Unicode"]
+git-tree-sha1 = "81690084b6198a2e1da36fcfda16eeca9f9f24e4"
+uuid = "682c06a0-de6a-54ab-a142-c8b1cf79cde6"
+version = "0.21.1"
+
+[[LibCURL]]
+deps = ["LibCURL_jll", "MozillaCACerts_jll"]
+uuid = "b27032c2-a3e7-50c8-80cd-2d36dbcbfd21"
+
+[[LibCURL_jll]]
+deps = ["Artifacts", "LibSSH2_jll", "Libdl", "MbedTLS_jll", "Zlib_jll", "nghttp2_jll"]
+uuid = "deac9b47-8bc7-5906-a0fe-35ac56dc84c0"
+
 [[LibGit2]]
+deps = ["Base64", "NetworkOptions", "Printf", "SHA"]
 uuid = "76f85450-5226-5b5a-8eaa-529ad045b433"
 
+[[LibSSH2_jll]]
+deps = ["Artifacts", "Libdl", "MbedTLS_jll"]
+uuid = "29816b5a-b9ab-546f-933c-edad1886dfa8"
+
+[[Libdl]]
+uuid = "8f399da3-3557-5675-b5ff-fb832c97cbdb"
+
 [[Logging]]
 uuid = "56ddb016-857b-54e1-b83d-db4d58db5568"
 
 [[Markdown]]
 deps = ["Base64"]
 uuid = "d6f4376e-aef5-505a-96c1-9c027394607a"
 
+[[MbedTLS_jll]]
+deps = ["Artifacts", "Libdl"]
+uuid = "c8ffd9c3-330d-5841-b78e-0817d7145fa1"
+
+[[Mmap]]
+uuid = "a63ad114-7e13-5084-954f-fe012c677804"
+
+[[MozillaCACerts_jll]]
+uuid = "14a3606d-f60d-562e-9121-12d972cd8159"
+
+[[NetworkOptions]]
+uuid = "ca575930-c2e3-43a9-ace4-1e988b2c1908"
+
+[[Parsers]]
+deps = ["Dates"]
+git-tree-sha1 = "c8abc88faa3f7a3950832ac5d6e690881590d6dc"
+uuid = "69de0a69-1ddd-5017-9359-2bf0b02dc9f0"
+version = "1.1.0"
+
 [[Pkg]]
-deps = ["Dates", "LibGit2", "Markdown", "Printf", "REPL", "Random", "SHA", "UUIDs"]
+deps = ["Artifacts", "Dates", "Downloads", "LibGit2", "Libdl", "Logging", "Markdown", "Printf", "REPL", "Random", "SHA", "Serialization", "TOML", "Tar", "UUIDs", "p7zip_jll"]
 uuid = "44cfe95a-1eb2-52ea-b672-e2afdf69b78f"
 
 [[Printf]]
 deps = ["Unicode"]
 uuid = "de0858da-6303-5e67-8744-51eddeeeb8d7"
 
 [[REPL]]
-deps = ["InteractiveUtils", "Markdown", "Sockets"]
+deps = ["InteractiveUtils", "Markdown", "Sockets", "Unicode"]
 uuid = "3fa0cd96-eef1-5676-8a61-b3b8758bbffb"
 
 [[Random]]
@@ -62,8 +115,16 @@ uuid = "9e88b42a-f829-5b0c-bbe9-9e923198166b"
 [[Sockets]]
 uuid = "6462fe0b-24de-5631-8697-dd941f90decc"
 
+[[TOML]]
+deps = ["Dates"]
+uuid = "fa267f1f-6049-4f14-aa54-33bafae1ed76"
+
+[[Tar]]
+deps = ["ArgTools", "SHA"]
+uuid = "a4e569a6-e804-4fa4-b0f3-eef7a1d5b13e"
+
 [[Test]]
-deps = ["Distributed", "InteractiveUtils", "Logging", "Random"]
+deps = ["InteractiveUtils", "Logging", "Random", "Serialization"]
 uuid = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
 
 [[UUIDs]]
@@ -72,3 +133,15 @@ uuid = "cf7118a7-6976-5b1a-9a39-7adc72f591a4"
 
 [[Unicode]]
 uuid = "4ec0a83e-493e-50e2-b9ac-8f72acf5a8f5"
+
+[[Zlib_jll]]
+deps = ["Libdl"]
+uuid = "83775a58-1f1d-513f-b197-d71354ab007a"
+
+[[nghttp2_jll]]
+deps = ["Artifacts", "Libdl"]
+uuid = "8e850ede-7688-5339-a07c-302acd2aaf8d"
+
+[[p7zip_jll]]
+deps = ["Artifacts", "Libdl"]
+uuid = "3f19e933-33d8-53b3-aaab-bd5110c3b7a0"

docs/make.jl

@@ -3,11 +3,16 @@ using GitForge
 
 makedocs(;
     modules=[GitForge],
-    format=Documenter.HTML(),
-    pages=["Home" => "index.md"],
-    repo="https://github.com/christopher-dG/GitForge.jl/blob/{commit}{path}#L{line}",
+    authors="Chris de Graaf <[email protected]>",
+    repo="https://github.com/JuliaWeb/GitForge.jl/blob/{commit}{path}#{line}",
     sitename="GitForge.jl",
-    authors="Chris de Graaf",
+    format=Documenter.HTML(;
+        canonical="https://juliaweb.github.io/GitForge.jl",
+        assets=String[],
+    ),
+    pages=[
+        "Home" => "index.md",
+    ],
 )
 
-deploydocs(; repo="github.com/christopher-dG/GitForge.jl")
+deploydocs(; repo="github.com/JuliaWeb/GitForge.jl")

docs/src/index.md

@@ -34,13 +34,18 @@ GitLab.PersonalAccessToken
 
 # API
 
-## Results
+Each API function ([`get_user`](@ref), [`get_repo`](@ref), etc.) returns a `Tuple{T, HTTP.Response}`.
+The value of `T` depends on what function you've called.
+For example, `get_user` will generally return some `User` type for your forge.
+
+When things go wrong, exceptions are thrown.
+They will always be one of the following types:
 
 ```@docs
-Result
-value
-response
-exception
+ForgeError
+HTTPError
+PostProcessorError
+RateLimitedError
 ```
 
 ## Pagination
@@ -67,6 +72,7 @@ get_file_contents
 get_pull_request
 get_pull_requests
 create_pull_request
+update_pull_request
 get_commit
 get_tags
 is_collaborator
@@ -116,7 +122,6 @@ These functions and types handle certain generic rate limiters.
 ```@docs
 RateLimiter
 OnRateLimit
-RateLimited
 has_rate_limits
 rate_limit_check
 on_rate_limit

src/GitForge.jl

@@ -1,8 +1,11 @@
 module GitForge
 
-using Dates
-using HTTP
-using JSON2
+using Base.Iterators: Pairs
+using Base.StackTraces: StackTrace
+
+using Dates: Period, UTC, now
+using HTTP: HTTP
+using JSON2: JSON2
 
 const AStr = AbstractString
 const HEADERS = ["Content-Type" => "application/json"]

src/forge.jl

@@ -116,7 +116,7 @@ rate_limit_check(::Forge, ::Function) = false
 
 Returns an [`OnRateLimit`](@ref) that determines how to react to an exceeded rate limit.
 """
-on_rate_limit(::Forge, ::Function) = ORL_RETURN
+on_rate_limit(::Forge, ::Function) = ORL_THROW
 
 """
     rate_limit_wait(::Forge, ::Function)