Default blpAuthenticate object support redux

ChangeLog

@@ -1,3 +1,23 @@
+2019-05-23  James Bell  <jamesbell@gmx.com>
+
+	* NAMESPACE: export new function defaultAuthentication()
+
+	* vignettes/rblpapi-intro.Rmd: document blpAutoAuthenticate
+	clarify host (blpConnect) vs hostname (blpAuthenticate) vs ip.address
+	clarify UUID, Application-Name, blpConnnect() and blpAuthenicate()
+
+	* R/defaultAuthentication.R: New file
+	Add default identity object
+	* R/blpAuthenticate.R: add default identity object
+	documentation clarification host vs ip
+	* R/init.R: check for auto-auth, call as needed
+
+	* R/bdh.R: support default identity object
+	* R/bdp.R: Idem
+	* R/bds.R: Idem
+	* R/portfolio.R.R: Idem
+	* R/subscribe.R: Idem
+
 2019-04-02  Dirk Eddelbuettel  <edd@debian.org>
 
 	* DESCRIPTION (Version, Date): New release 0.3.10

NAMESPACE

@@ -5,6 +5,7 @@ importFrom("utils", "object.size", "packageVersion")
 export("blpConnect",
        "blpDisconnect",
        "defaultConnection",
+       "defaultAuthentication",
        "blpAuthenticate",
        "bdp",
        "bdh",

R/bdh.R

@@ -38,7 +38,9 @@
 ##' being set) as well as a value.
 ##' @param verbose A boolean indicating whether verbose operation is
 ##' desired, defaults to \sQuote{FALSE}
-##' @param identity An optional identity object.
+##' @param identity An optional identity object as created by a
+##' \code{blpAuthenticate} call, and retrived via the internal function
+##' \code{defaultAuthentication}.
 ##' @param con A connection object as created by a \code{blpConnect}
 ##' call, and retrieved via the internal function
 ##' \code{defaultConnection}.
@@ -82,7 +84,7 @@
 ##' }
 bdh <- function(securities, fields, start.date, end.date=NULL,
                 include.non.trading.days=FALSE, options=NULL, overrides=NULL,
-                verbose=FALSE, identity=NULL, con=defaultConnection(),
+                verbose=FALSE, identity=defaultAuthentication(), con=defaultConnection(),
                 int.as.double=getOption("blpIntAsDouble", FALSE)) {
     if (class(start.date) == "Date") {
         start.date <- format(start.date, format="%Y%m%d")

R/bdp.R

@@ -33,7 +33,9 @@
 ##' being set) as well as a value.
 ##' @param verbose A boolean indicating whether verbose operation is
 ##' desired, defaults to \sQuote{FALSE}
-##' @param identity An optional identity object.
+##' @param identity An optional identity object as created by a
+##' \code{blpAuthenticate} call, and retrived via the internal function
+##' \code{defaultAuthentication}.
 ##' @param con A connection object as created by a \code{blpConnect}
 ##' call, and retrieved via the internal function
 ##' \code{defaultConnection}.
@@ -52,7 +54,7 @@
 ##'   bdp("SPX Index", "INTERVAL_AVG", overrides=ovrd)
 ##' }
 bdp <- function(securities, fields, options=NULL, overrides=NULL,
-                verbose=FALSE, identity=NULL, con=defaultConnection()) {
+                verbose=FALSE, identity=defaultAuthentication(), con=defaultConnection()) {
     if (any(duplicated(securities))) stop("Duplicated securities submitted.", call.=FALSE)
     bdp_Impl(con, securities, fields, options, overrides, verbose, identity)
 }

R/bds.R

@@ -33,7 +33,9 @@
 ##' being set) as well as a value.
 ##' @param verbose A boolean indicating whether verbose operation is
 ##' desired, defaults to \sQuote{FALSE}
-##' @param identity An optional identity object.
+##' @param identity An optional identity object as created by a
+##' \code{blpAuthenticate} call, and retrived via the internal function
+##' \code{defaultAuthentication}.
 ##' @param con A connection object as created by a \code{blpConnect}
 ##' call, and retrieved via the internal function
 ##' \code{defaultConnection}.
@@ -53,7 +55,7 @@
 ##' }
 bds <- function(security, field, options=NULL,
                 overrides=NULL, verbose=FALSE,
-                identity=NULL, con=defaultConnection()) {
+                identity=defaultAuthentication(), con=defaultConnection()) {
     if (length(security) != 1L)
         stop("more than one security submitted.", call.=FALSE)
     if (length(field) != 1L)

R/blpAuthenticate.R

@@ -21,37 +21,70 @@
 ##' This function authenticates against the the Bloomberg API
 ##'
 ##' @title Authenticate Bloomberg API access
-##' @param uuid A character variable with a unique user id token. If this
-##' is missing the function will attempt to connect to bpipe using the connection. It
-##' is assumed that an app_name was set. See blpConnect() for app_name information
-##' @param host A character variable with a hostname, defaults to 'localhost'
+##' @param uuid An optional character variable with a unique user id
+##'     token. If this is missing the function will attempt to connect
+##'     to B-PIPE or SAPI using the connection. It is assumed that an
+##'     app_name was set. See \code{blpConnect()} for app_name
+##'     information.  Defaults to \code{getOption("blpUUID")} or NULL
+##' @param host An optional character variable with a hostname.  This is
+##'     the hostname of the machine where the user last authenticated.
+##'     Either host or ip.address should be provided for user/uuid
+##'     authentication. Note this is likely not the same 'host' used in
+##'     \code{blpConnect()}.  Defaults to
+##'     \code{getOption("blpLoginHostname")} or "localhost"
 ##' @param ip.address An optional character variable with an IP address
+##'     for authentication.  Usually the IP address where the uuid/user
+##'     last logged into the Bloomberg Terminal appication.  Defaults to
+##'     \code{getOption("blpLoginIP")} or NULL, which will then lookup
+##'     the IP of the "host" option. 
 ##' @param con A connection object as created by a \code{blpConnect}
 ##' call, and retrieved via the internal function. This is the only required
-##' argument to authenticate a bpipe connection with a appName.
-##' \code{defaultConnection}.
-##' @return The returned object should be passed to subsequent data
-##' calls via bdp(), bds(), etc.
+##' argument to authenticate a B-PIPE connection with a appName.
+##' Defaults to \code{defaultConnection}.
+##' @param default A logical indicating whether this authentication should
+##' be saved as the default, as opposed to returned to the
+##' user. Default to \code{TRUE}.
+##' @return In the \code{default=TRUE} case nothing is returned, and
+##' this authentication is automatically used for all future calls which
+##' omit the \code{identity} argument. Otherwise an authentication object is
+##' returned which is required by all the accessor functions in the
+##' package. (e.g. \code{bdp()} \code{bds()} \code{getPortfolio()} 
 ##' @author Whit Armstrong and Dirk Eddelbuettel
 ##' @examples
 ##' \dontrun{
 ##' blpConnect(host=blpHost, port=blpPort)
+##' blpAuthenticate(uuid=blpUUID, ip=blpIP_address)
+##' bdp("IBM US Equity", "NAME")
+##'
 ##' blpid <- blpAuthenticate(uuid=blpUUID, ip=blpIP_address)
 ##' bdp("IBM US Equity", "NAME", identity=blpid)
 ##' }
 
-blpAuthenticate <- function(uuid, host="localhost", ip.address, con=defaultConnection()) {
-    if(missing(uuid)) {
-        ## no UUID, assume BPIPE
-        authenticate_Impl(con, NULL, NULL)
+blpAuthenticate <- function(uuid=getOption("blpUUID", NULL),
+                            host=getOption("blpLoginHostname", "localhost"),
+                            ip.address=getOption("blpLoginIP", NULL),
+                            con=defaultConnection(),
+                            default=TRUE) {
+    if(is.null(uuid)) {
+        ## no UUID, assume B-PIPE or SAPI with application ID
+        blpAuth <- authenticate_Impl(con, NULL, NULL)
     } else {
+        if ( (!is.null(ip.address)) && (!identical(host,"localhost")) ) {
+            warning("Both ip.address and host are set.  Using ip.address.") }
+
         ## have UUID, assume SAPI
-        if (missing(ip.address)) {
+        if (is.null(ip.address)) {
             ## Linux only ?
             cmd.res <- system(paste("host",host), intern=TRUE,
                               ignore.stdout=FALSE, ignore.stderr=FALSE,wait=TRUE)
             ip.address <- strsplit(cmd.res,"address ")[[1]][2]
         }
-        authenticate_Impl(con, as.character(uuid), ip.address)
+        blpAuth <- authenticate_Impl(con, as.character(uuid), ip.address)
     }
+    ## if we're setting the silent/hidden default object, return nothing
+    ## else, return the object (keeps old behavior)
+    if (default)
+        .pkgenv$blpAuth <- blpAuth
+    else
+        return(blpAuth)
 }

R/defaults.R

@@ -0,0 +1,62 @@
+
+##
+##  Copyright (C) 2019  Whit Armstrong and Dirk Eddelbuettel and John Laing
+##
+##  This file is part of Rblpapi
+##
+##  Rblpapi is free software: you can redistribute it and/or modify
+##  it under the terms of the GNU General Public License as published by
+##  the Free Software Foundation, either version 2 of the License, or
+##  (at your option) any later version.
+##
+##  Rblpapi is distributed in the hope that it will be useful,
+##  but WITHOUT ANY WARRANTY; without even the implied warranty of
+##  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+##  GNU General Public License for more details.
+##
+##  You should have received a copy of the GNU General Public License
+##  along with Rblpapi.  If not, see <http://www.gnu.org/licenses/>.
+
+
+##' These functions return the default connection/authentication objects
+##' from the package environment.  If no default connection/authentication
+##' has been established yet, will return NULL.
+##' In the case of authentication, if using a desktop/workstation
+##' session, NULL will work fine.  If using SAPI/Bpipe, you may need
+##' to use blpAuthenticate() to create an authentication object.
+##'
+##' @title Return the default connection/authentication objects
+##'
+##' @details Required arguments can be set via \code{\link{options}}. See
+##' \code{\link{blpConnect}} and \code{\link{blpAuthenticate}} for details.
+##' In addition, if options \code{blpAutoConnect} and/or
+##' \code{blpAutoAuthenticate} are set to \sQuote{TRUE}, a connection and/or
+##' authentication is established in the \code{.onAttach()} function and
+##' stored in the package environment. This effectively frees users from
+##' having to explicitly create such objects. Of course, the user can also
+##' call \code{blpConnect} and/or \code{blpAuthenticate} explicitly and
+##' store the connection/authentication objects. These helper functions
+##' look up the stored connection/authentications object and return them.
+##' In case no connection has been established, an error message is shown.
+##' In case no authentication has been established, NULL is returned.
+##' (NULL is sufficent for Desktop API connections.)
+##'
+##' @author Whit Armstrong and Dirk Eddelbuettel
+##' @examples
+##' \dontrun{
+##'   con <- defaultConnection()
+##'   blpid <- defaultAuthentication()
+##' }
+##' @rdname defaults
+defaultConnection <- function() {
+    con <- .pkgenv$con
+    if (is.null(con))
+        stop("No connection object has been created. Use 'blpConnect()' first.",
+             call.=FALSE)
+    con
+}
+##' @rdname defaults
+defaultAuthentication <- function() {
+    blpAuth <- .pkgenv$blpAuth
+    blpAuth
+}

R/init.R

@@ -26,7 +26,7 @@
                                  " and run-time ", getRuntimeVersion(), "."))
     packageStartupMessage(paste0("Please respect the Bloomberg licensing agreement ",
                                  "and terms of service."))
-    
+
     if (getOption("blpAutoConnect", FALSE)) {
         con <- blpConnect()
         if (getOption("blpVerbose", FALSE)) {
@@ -35,5 +35,14 @@
     } else {
         con <- NULL
     }
+    if (getOption("blpAutoAuthenticate", FALSE)) {
+        blpAuth <- blpAuthenticate()
+        if (getOption("blpVerbose", FALSE)) {
+            packageStartupMessage("Created and stored default authentication object.")
+        }
+    } else {
+        blpAuth <- NULL
+    }
     assign("con", con, envir=.pkgenv)
+    assign("blpAuth", blpAuth, envir=.pkgenv)
 }

R/portfolio.R

@@ -32,7 +32,9 @@
 ##' being set) as well as a value.
 ##' @param verbose A boolean indicating whether verbose operation is
 ##' desired, defaults to \sQuote{FALSE}
-##' @param identity An optional identity object.
+##' @param identity An optional identity object as created by a
+##' \code{blpAuthenticate} call, and retrived via the internal function
+##' \code{defaultAuthentication}.
 ##' @param con A connection object as created by a \code{blpConnect}
 ##' call, and retrieved via the internal function
 ##' \code{defaultConnection}.
@@ -45,7 +47,7 @@
 ## TODO: examples. Do global portfolios exist so that examples will
 ##       work for everyone? Otherwise I don't know how to do this.
 getPortfolio <- function(security, field, options=NULL, overrides=NULL,
-                      verbose=FALSE, identity=NULL,
+                      verbose=FALSE, identity=defaultAuthentication(),
                       con=defaultConnection()) {
     if (length(security) != 1L)
         stop("more than one security submitted.", call.=FALSE)

R/subscribe.R

@@ -36,7 +36,9 @@
 ##' @param options An optional named character vector with option
 ##' values. Each field must have both a name (designating the option
 ##' being set) as well as a value.
-##' @param identity An optional identity object.
+##' @param identity An optional identity object as created by a
+##' \code{blpAuthenticate} call, and retrived via the internal function
+##' \code{defaultAuthentication}.
 ##' @param con A connection object as created by a \code{blpConnect}
 ##' call, and retrieved via the internal function
 ##' \code{defaultConnection}.
@@ -49,7 +51,7 @@
 ##'             fields=c("LAST_PRICE","BID","ASK"),
 ##'             fun=function(x) print(str(x$data)))
 ##' }
-subscribe <- function(securities, fields, fun, options=NULL, identity=NULL, con=defaultConnection()) {
+subscribe <- function(securities, fields, fun, options=NULL, identity=defaultAuthentication(), con=defaultConnection()) {
     if (any(duplicated(securities))) stop("Duplicated securities submitted.", call.=FALSE)
     subscribe_Impl(con, securities, fields, fun, options, identity)
 }