Merge pull request #441 from lread/lread-declare-public-api

Declare the etaoin public API

CHANGELOG.adoc

@@ -9,10 +9,38 @@ A release with an intentional breaking changes is marked with:
 
 Minor Breaking Changes
 
-* https://github.com/clj-commons/etaoin/issues/412[#412]: Rename `etaoin.keys/num-.` to `etaoin.keys/num-dot` +
+* https://github.com/clj-commons/etaoin/issues/412[#412]: Rename `etaoin.keys/num-.` to `etaoin.keys/num-dot`. +
 The symbol `num-.` is technically an invalid Clojure symbol and can confuse tooling. +
 A grep.app for `num-.` found Etaoin itself as the only user of this var.
 If your code uses `etaoin.keys/num-.`, you'll need to rename it to `etaoin.keys/num-dot`.
+* https://github.com/clj-commons/etaoin/issues/430[#430]: Declare the public API.
+We made what we think is a good guess at what the public etaoin API is.
+The following namespaces are now considered internal and subject to change:
++
+[%autowidth]
+|===
+| old namespace | new internal namespace
+
+| `etaoin.client`
+| `etaoin.impl.client`
+
+| `etaoin.driver`
+| `etaoin.impl.driver`
+
+| `etaoin.proc`
+| `etaoin.impl.proc`
+
+| `etaoin.xpath`
+| `etaoin.impl.xpath`
+
+| `etaoin.ide.api`
+| `etaoin.ide.impl.api`
+
+| `etaoin.ide.spec`
+| `etaoin.ide.impl.spec`
+
+|===
+If we got this wrong your code will fail, you will tell us, and we can discuss.
 
 Other Changes
 

src/etaoin/api.clj

@@ -17,13 +17,13 @@
   Phantom.js (Ghostdriver) - obsolete and no longer tested
   https://github.com/detro/ghostdriver/blob/
   "
-  (:require [etaoin.proc   :as proc]
-            [etaoin.client :as client]
+  (:require [etaoin.impl.proc   :as proc]
+            [etaoin.impl.client :as client]
             [etaoin.keys   :as keys]
             [etaoin.query  :as query]
             [etaoin.util   :as util :refer [defmethods]]
-            [etaoin.driver :as drv]
-            [etaoin.xpath  :as xpath]
+            [etaoin.impl.driver :as drv]
+            [etaoin.impl.xpath  :as xpath]
 
             [clojure.tools.logging     :as log]
             [clojure.java.io           :as io]

src/etaoin/ide/flow.clj

@@ -7,8 +7,8 @@
    [clojure.set :as cset]
    [clojure.spec.alpha :as s]
    [etaoin.api :refer :all]
-   [etaoin.ide.api :refer [run-command-with-log str->var]]
-   [etaoin.ide.spec :as spec]))
+   [etaoin.ide.impl.api :refer [run-command-with-log str->var]]
+   [etaoin.ide.impl.spec :as spec]))
 
 
 (declare execute-commands)

src/etaoin/ide/api.clj → src/etaoin/ide/impl/api.clj

@@ -1,4 +1,4 @@
-(ns etaoin.ide.api
+(ns ^:no-doc etaoin.ide.impl.api
   "
   Common Selenium IDE implementation.
   https://www.selenium.dev/selenium-ide/docs/en/api/commands

src/etaoin/ide/spec.clj → src/etaoin/ide/impl/spec.clj

@@ -1,4 +1,4 @@
-(ns etaoin.ide.spec
+(ns ^:no-doc etaoin.ide.impl.spec
   "
   Parsing IDE flow with spec.
   "

src/etaoin/client.cljc → src/etaoin/impl/client.cljc

@@ -1,4 +1,4 @@
-(ns etaoin.client
+(ns ^:no-doc etaoin.impl.client
   (:require [clojure.string :as str]
             [clojure.tools.logging :as log]
             #?(:bb [clj-http.lite.client :as client]

src/etaoin/driver.clj → src/etaoin/impl/driver.clj

@@ -1,4 +1,4 @@
-(ns etaoin.driver
+(ns ^:no-doc etaoin.impl.driver
   "Some utilities to work with driver's data structure.
 
   Links for development:

src/etaoin/proc.clj → src/etaoin/impl/proc.clj

@@ -1,4 +1,4 @@
-(ns etaoin.proc
+(ns ^:no-doc etaoin.impl.proc
   (:require [clojure.java.io :as io]
             [clojure.string :as str]))
 

src/etaoin/xpath.clj → src/etaoin/impl/xpath.clj

@@ -1,4 +1,4 @@
-(ns etaoin.xpath
+(ns ^:no-doc etaoin.impl.xpath
   "A special module to work with XPath language."
   (:require [clojure.string :as string]))
 

src/etaoin/query.clj

@@ -1,7 +1,7 @@
 (ns etaoin.query
   "A module to deal with querying elements."
   (:require [etaoin.util :as util]
-            [etaoin.xpath :as xpath]))
+            [etaoin.impl.xpath :as xpath]))
 
 ;; todo duplicates with api.clj
 (def locator-xpath "xpath")

test/etaoin/unit/proc_test.clj

@@ -2,7 +2,7 @@
   (:require [etaoin.api :refer :all]
             [clojure.java.shell :refer [sh]]
             [clojure.test :refer :all]
-            [etaoin.proc :as proc]
+            [etaoin.impl.proc :as proc]
             [etaoin.test-report]
             [clojure.pprint :as pprint]
             [clojure.string :as str]))

test/etaoin/unit/unit_test.clj

@@ -4,16 +4,16 @@
             [clojure.test :refer :all]
             [etaoin.api :refer :all]
             [etaoin.ide.flow :as ide]
-            [etaoin.ide.spec :as spec]
+            [etaoin.ide.impl.spec :as spec]
             [etaoin.test-report]
-            etaoin.proc))
+            etaoin.impl.proc))
 
 (deftest test-firefox-driver-args
   (with-redefs
-    [etaoin.proc/run  (fn [_ _])
+    [etaoin.impl.proc/run  (fn [_ _])
      wait-running     identity
      create-session   (fn [_ _] "session-key")
-     etaoin.proc/kill identity
+     etaoin.impl.proc/kill identity
      delete-session   identity]
     (testing "Session"
       (with-firefox {} driver

test/etaoin/unit/xpath_test.clj

@@ -1,7 +1,7 @@
 (ns etaoin.unit.xpath-test
   (:require [clojure.test :refer :all]
             [etaoin.test-report]
-            [etaoin.xpath :as xpath]))
+            [etaoin.impl.xpath :as xpath]))
 
 (def xpath-samples
   [[{:tag :a} ".//a"]