Prepare for release - v0.1.0 (#7)

* Update ExDoc and fix typespecs

* Prepare for first release

Author: Philip Sampaio

README.md

@@ -1,20 +1,49 @@
 # ReqCH
 
-A Req plugin for ClickHouse. 
+[![Docs](https://img.shields.io/badge/hex.pm-docs-8e7ce6.svg)](https://hexdocs.pm/req_ch)
+[![Hex pm](http://img.shields.io/hexpm/v/req_ch.svg?style=flat&color=blue)](https://hex.pm/packages/req_ch)
 
-## Installation
+A [Req](https://github.com/wojtekmach/req) plugin for [ClickHouse](https://clickhouse.com/).
 
-If [available in Hex](https://hex.pm/docs/publish), the package can be installed
-by adding `req_ch` to your list of dependencies in `mix.exs`:
+## Usage
+
+Assuming that you have a ClickHouse server running on localhost, this code is going to run:
 
 ```elixir
-def deps do
-  [
-    {:req_ch, "~> 0.1.0"}
-  ]
-end
+Mix.install([
+  {:req_ch, "~> 0.1.0"}
+])
+
+req = ReqCH.new(database: "system")
+
+ReqCH.query!(req, "SELECT number FROM numbers LIMIT 5").body
+# => "0\n1\n2\n3\n4\n"
+
+ReqCH.query!(req, "SELECT number FROM numbers WHERE number > {num:UInt8} LIMIT 5", [num: 12]).body
+# => "13\n14\n15\n16\n17\n"
 ```
 
+It's also possible to return `Explorer` dataframes, if the `:explorer` package is installed
+and the `:explorer` format is used:
+
+```elixir
+Mix.install([
+  {:req_ch, "~> 0.1.0"},
+  {:explorer, "~> 0.10.0"}
+])
+
+req = ReqCH.new(database: "system")
+
+ReqCH.query!(req, "SELECT number, number - 2 as less_two FROM numbers LIMIT 5", [], [format: :explorer]).body
+# => #Explorer.DataFrame<
+#   Polars[5 x 2]
+#   number u64 [0, 1, 2, 3, 4]
+#   less_two s64 [-2, -1, 0, 1, 2]
+# >
+```
+
+See the [documentation](https://hexdocs.pm/req_ch) for details.
+
 ## License
 
 Copyright (C) 2024 Dashbit

lib/req_ch.ex

@@ -29,6 +29,7 @@ defmodule ReqCH do
       This option accepts `:tsv`, `:csv`, `:json` or `:explorer` as atoms.
 
       It also accepts all formats described in the #{@formats_page} page.
+      Use plain strings for these formats.
 
       The `:explorer` format is special, and will build an Explorer dataframe
       in case the `:explorer` dependency is installed.
@@ -41,14 +42,14 @@ defmodule ReqCH do
   After setting a default database, one can make a request directly:
 
       iex> req = ReqCH.new(database: "system")
-      iex> Req.post!(req, body: "SELECT number FROM numbers LIMIT 3").body
-      1\n2\n3\n
+      iex> Req.post!(req, body: "SELECT number + 1 FROM numbers LIMIT 3").body
+      "1\\n2\\n3\\n"
 
   It's also possible to make a query using `Req.get/2`:
 
       iex> req = ReqCH.new(database: "system")
-      iex> Req.get!(req, params: [query: "SELECT number FROM numbers LIMIT 3"]).body
-      1\n2\n3\n
+      iex> Req.get!(req, params: [query: "SELECT number + 1 FROM numbers LIMIT 3"]).body
+      "1\\n2\\n3\\n"
 
   In case the server needs authentication, it's possible to use `Req` options for that.
 
@@ -122,9 +123,9 @@ defmodule ReqCH do
 
   """
   @spec query(
-          Req.t(),
+          Req.Request.t(),
           sql_query :: binary(),
-          sql_query_params :: Map.t() | Keyword.t(),
+          sql_query_params :: map() | Keyword.t(),
           opts :: Keyword.t()
         ) :: {:ok, Req.Response.t()} | {:error, binary()}
   def query(req, sql_query, sql_query_params \\ [], opts \\ [])
@@ -141,9 +142,9 @@ defmodule ReqCH do
   Same as `query/4`, but raises in case of error.
   """
   @spec query!(
-          Req.t(),
+          Req.Request.t(),
           sql_query :: binary(),
-          sql_query_params :: Map.t() | Keyword.t(),
+          sql_query_params :: map() | Keyword.t(),
           opts :: Keyword.t()
         ) :: Req.Response.t()
   def query!(req, sql_query, sql_query_params \\ [], opts \\ [])

mix.exs

@@ -11,23 +11,45 @@ defmodule ReqCH.MixProject do
       name: "ReqCH",
       description: "A minimal Req plugin for ClickHouse",
       start_permanent: Mix.env() == :prod,
+      preferred_cli_env: [
+        docs: :docs,
+        "hex.publish": :docs
+      ],
+      docs: docs(),
+      package: package(),
       deps: deps()
     ]
   end
 
-  # Run "mix help compile.app" to learn about applications.
   def application do
     [
       extra_applications: [:logger]
     ]
   end
 
-  # Run "mix help deps" to learn about dependencies.
   defp deps do
     [
       {:req, "~> 0.5"},
       {:explorer, "~> 0.10", optional: true},
       {:ex_doc, ">= 0.0.0", only: :docs, runtime: false}
     ]
   end
+
+  defp package do
+    [
+      licenses: ["Apache-2.0"],
+      links: %{
+        "GitHub" => "https://github.com/livebook-dev/req_ch"
+      }
+    ]
+  end
+
+  defp docs do
+    [
+      main: "readme",
+      source_url: "https://github.com/livebook-dev/req_ch",
+      source_ref: "v#{@version}",
+      extras: ["README.md"]
+    ]
+  end
 end

mix.lock

@@ -1,16 +1,16 @@
 %{
   "aws_signature": {:hex, :aws_signature, "0.3.2", "adf33bc4af00b2089b7708bf20e3246f09c639a905a619b3689f0a0a22c3ef8f", [:rebar3], [], "hexpm", "b0daf61feb4250a8ab0adea60db3e336af732ff71dd3fb22e45ae3dcbd071e44"},
-  "castore": {:hex, :castore, "1.0.9", "5cc77474afadf02c7c017823f460a17daa7908e991b0cc917febc90e466a375c", [:mix], [], "hexpm", "5ea956504f1ba6f2b4eb707061d8e17870de2bee95fb59d512872c2ef06925e7"},
-  "decimal": {:hex, :decimal, "2.1.1", "5611dca5d4b2c3dd497dec8f68751f1f1a54755e8ed2a966c2633cf885973ad6", [:mix], [], "hexpm", "53cfe5f497ed0e7771ae1a475575603d77425099ba5faef9394932b35020ffcc"},
+  "castore": {:hex, :castore, "1.0.10", "43bbeeac820f16c89f79721af1b3e092399b3a1ecc8df1a472738fd853574911", [:mix], [], "hexpm", "1b0b7ea14d889d9ea21202c43a4fa015eb913021cb535e8ed91946f4b77a8848"},
+  "decimal": {:hex, :decimal, "2.2.0", "df3d06bb9517e302b1bd265c1e7f16cda51547ad9d99892049340841f3e15836", [:mix], [], "hexpm", "af8daf87384b51b7e611fb1a1f2c4d4876b65ef968fa8bd3adf44cff401c7f21"},
   "earmark_parser": {:hex, :earmark_parser, "1.4.41", "ab34711c9dc6212dda44fcd20ecb87ac3f3fce6f0ca2f28d4a00e4154f8cd599", [:mix], [], "hexpm", "a81a04c7e34b6617c2792e291b5a2e57ab316365c2644ddc553bb9ed863ebefa"},
-  "ex_doc": {:hex, :ex_doc, "0.34.2", "13eedf3844ccdce25cfd837b99bea9ad92c4e511233199440488d217c92571e8", [:mix], [{:earmark_parser, "~> 1.4.39", [hex: :earmark_parser, repo: "hexpm", optional: false]}, {:makeup_c, ">= 0.1.0", [hex: :makeup_c, repo: "hexpm", optional: true]}, {:makeup_elixir, "~> 0.14 or ~> 1.0", [hex: :makeup_elixir, repo: "hexpm", optional: false]}, {:makeup_erlang, "~> 0.1 or ~> 1.0", [hex: :makeup_erlang, repo: "hexpm", optional: false]}, {:makeup_html, ">= 0.1.0", [hex: :makeup_html, repo: "hexpm", optional: true]}], "hexpm", "5ce5f16b41208a50106afed3de6a2ed34f4acfd65715b82a0b84b49d995f95c1"},
+  "ex_doc": {:hex, :ex_doc, "0.35.1", "de804c590d3df2d9d5b8aec77d758b00c814b356119b3d4455e4b8a8687aecaf", [:mix], [{:earmark_parser, "~> 1.4.39", [hex: :earmark_parser, repo: "hexpm", optional: false]}, {:makeup_c, ">= 0.1.0", [hex: :makeup_c, repo: "hexpm", optional: true]}, {:makeup_elixir, "~> 0.14 or ~> 1.0", [hex: :makeup_elixir, repo: "hexpm", optional: false]}, {:makeup_erlang, "~> 0.1 or ~> 1.0", [hex: :makeup_erlang, repo: "hexpm", optional: false]}, {:makeup_html, ">= 0.1.0", [hex: :makeup_html, repo: "hexpm", optional: true]}], "hexpm", "2121c6402c8d44b05622677b761371a759143b958c6c19f6558ff64d0aed40df"},
   "explorer": {:hex, :explorer, "0.10.0", "ba690afb59fce81746a1b6c9d25294aabcb9bae783ceeb43f5fd4834e1e16d78", [:mix], [{:adbc, "~> 0.1", [hex: :adbc, repo: "hexpm", optional: true]}, {:aws_signature, "~> 0.3", [hex: :aws_signature, repo: "hexpm", optional: false]}, {:castore, "~> 1.0", [hex: :castore, repo: "hexpm", optional: true]}, {:decimal, "~> 2.1", [hex: :decimal, repo: "hexpm", optional: false]}, {:flame, "~> 0.3", [hex: :flame, repo: "hexpm", optional: true]}, {:fss, "~> 0.1", [hex: :fss, repo: "hexpm", optional: false]}, {:nx, "~> 0.4", [hex: :nx, repo: "hexpm", optional: true]}, {:rustler, "~> 0.34.0", [hex: :rustler, repo: "hexpm", optional: true]}, {:rustler_precompiled, "~> 0.7", [hex: :rustler_precompiled, repo: "hexpm", optional: false]}, {:table, "~> 0.1.2", [hex: :table, repo: "hexpm", optional: false]}, {:table_rex, "~> 3.1.1 or ~> 4.0.0", [hex: :table_rex, repo: "hexpm", optional: false]}], "hexpm", "874b6af1f711186f391b507af293995f89311821486e01cbca4c99777ff20864"},
   "finch": {:hex, :finch, "0.19.0", "c644641491ea854fc5c1bbaef36bfc764e3f08e7185e1f084e35e0672241b76d", [:mix], [{:mime, "~> 1.0 or ~> 2.0", [hex: :mime, repo: "hexpm", optional: false]}, {:mint, "~> 1.6.2 or ~> 1.7", [hex: :mint, repo: "hexpm", optional: false]}, {:nimble_options, "~> 0.4 or ~> 1.0", [hex: :nimble_options, repo: "hexpm", optional: false]}, {:nimble_pool, "~> 1.1", [hex: :nimble_pool, repo: "hexpm", optional: false]}, {:telemetry, "~> 0.4 or ~> 1.0", [hex: :telemetry, repo: "hexpm", optional: false]}], "hexpm", "fc5324ce209125d1e2fa0fcd2634601c52a787aff1cd33ee833664a5af4ea2b6"},
   "fss": {:hex, :fss, "0.1.1", "9db2344dbbb5d555ce442ac7c2f82dd975b605b50d169314a20f08ed21e08642", [:mix], [], "hexpm", "78ad5955c7919c3764065b21144913df7515d52e228c09427a004afe9c1a16b0"},
   "hpax": {:hex, :hpax, "1.0.0", "28dcf54509fe2152a3d040e4e3df5b265dcb6cb532029ecbacf4ce52caea3fd2", [:mix], [], "hexpm", "7f1314731d711e2ca5fdc7fd361296593fc2542570b3105595bb0bc6d0fad601"},
   "jason": {:hex, :jason, "1.4.4", "b9226785a9aa77b6857ca22832cffa5d5011a667207eb2a0ad56adb5db443b8a", [:mix], [{:decimal, "~> 1.0 or ~> 2.0", [hex: :decimal, repo: "hexpm", optional: true]}], "hexpm", "c5eb0cab91f094599f94d55bc63409236a8ec69a21a67814529e8d5f6cc90b3b"},
-  "makeup": {:hex, :makeup, "1.1.2", "9ba8837913bdf757787e71c1581c21f9d2455f4dd04cfca785c70bbfff1a76a3", [:mix], [{:nimble_parsec, "~> 1.2.2 or ~> 1.3", [hex: :nimble_parsec, repo: "hexpm", optional: false]}], "hexpm", "cce1566b81fbcbd21eca8ffe808f33b221f9eee2cbc7a1706fc3da9ff18e6cac"},
-  "makeup_elixir": {:hex, :makeup_elixir, "0.16.2", "627e84b8e8bf22e60a2579dad15067c755531fea049ae26ef1020cad58fe9578", [:mix], [{:makeup, "~> 1.0", [hex: :makeup, repo: "hexpm", optional: false]}, {:nimble_parsec, "~> 1.2.3 or ~> 1.3", [hex: :nimble_parsec, repo: "hexpm", optional: false]}], "hexpm", "41193978704763f6bbe6cc2758b84909e62984c7752b3784bd3c218bb341706b"},
+  "makeup": {:hex, :makeup, "1.2.1", "e90ac1c65589ef354378def3ba19d401e739ee7ee06fb47f94c687016e3713d1", [:mix], [{:nimble_parsec, "~> 1.4", [hex: :nimble_parsec, repo: "hexpm", optional: false]}], "hexpm", "d36484867b0bae0fea568d10131197a4c2e47056a6fbe84922bf6ba71c8d17ce"},
+  "makeup_elixir": {:hex, :makeup_elixir, "1.0.0", "74bb8348c9b3a51d5c589bf5aebb0466a84b33274150e3b6ece1da45584afc82", [:mix], [{:makeup, "~> 1.0", [hex: :makeup, repo: "hexpm", optional: false]}, {:nimble_parsec, "~> 1.2.3 or ~> 1.3", [hex: :nimble_parsec, repo: "hexpm", optional: false]}], "hexpm", "49159b7d7d999e836bedaf09dcf35ca18b312230cf901b725a64f3f42e407983"},
   "makeup_erlang": {:hex, :makeup_erlang, "1.0.1", "c7f58c120b2b5aa5fd80d540a89fdf866ed42f1f3994e4fe189abebeab610839", [:mix], [{:makeup, "~> 1.0", [hex: :makeup, repo: "hexpm", optional: false]}], "hexpm", "8a89a1eeccc2d798d6ea15496a6e4870b75e014d1af514b1b71fa33134f57814"},
   "mime": {:hex, :mime, "2.0.6", "8f18486773d9b15f95f4f4f1e39b710045fa1de891fada4516559967276e4dc2", [:mix], [], "hexpm", "c9945363a6b26d747389aac3643f8e0e09d30499a138ad64fe8fd1d13d9b153e"},
   "mint": {:hex, :mint, "1.6.2", "af6d97a4051eee4f05b5500671d47c3a67dac7386045d87a904126fd4bbcea2e", [:mix], [{:castore, "~> 0.1.0 or ~> 1.0", [hex: :castore, repo: "hexpm", optional: true]}, {:hpax, "~> 0.1.1 or ~> 0.2.0 or ~> 1.0", [hex: :hpax, repo: "hexpm", optional: false]}], "hexpm", "5ee441dffc1892f1ae59127f74afe8fd82fda6587794278d924e4d90ea3d63f9"},