The ShinyBroker package, and the examples in the documentation, were created with PyCharm. You certainly do not have to use PyCharm, but it is used in this article series to make the material accessible to readers who aren't old hands at dealing with environments, versions, and packages. If you follow this tutorial and use PyCharm, you will not have to worry about any of that; if you don't, then it's assumed you know what you're doing and are comfortable with your own setup.

Use TWS unless you're already comfortable with IBG. ShinyBroker will work fine with IB Gateway, but it's recommended to start out with TraderWorkstation so that you can use its UI and menus to verify/follow along with whatever you're building in ShinyBroker.

Install the following:

• Trader Workstation (TWS) You probably already have TWS installed if you're reading this article but if not, install it from IBKR's website. You may use the Demo account if you don't own an account at IBKR.
• Python: You'll need Python, of course. Install the latest stable version.
• PyCharm: Download & install from JetBrains. The free community version is fine but if you are associated with a university, you might be interested in JetBrain's Student Pack which gives you free access to PyCharm Pro and a lot of other interesting tools.

Create a new PyCharm Project: We're going to set up a PyCharm project for this tutorial and instruct it to use one and only one dedicated installation of Python. This way, you don't have to deal with all sorts of compatability problems that may otherwise arise between different Python versions, libraries, and so on.

1. Open up PyCharm and create a new project. The "project" is simply a folder that stores all files related to this tutorial. You can name it whatever you want and store it in a convenient place on your computer. Give it a good, informative name that you like -- it's helpful.

2. Configure an Interpreter. You want to tell PyCharm to create a dedicated installation of Python only for use by this project, and you can do that by configuring an interpreter. You might have already created an environment for this project when you created a new project; if you did, then you'll see a folder named ".venv" in your project directory, like in the screenshot below:

   

   If your PyCharm project does not have an interpreter configured, then you will probably be prompted to create one via a clickable banner within PyCharm. If you can't find the banner or if you closed it, you can use the interpreter settings menu found under File > Settings. From the interpreter settings window, add a new local interpreter in your project folder. You should now see the ".venv" folder in your project directory like the one in the screenshot above. .venv contains the installation of Python that your project will use.

3. Verify that your project is using the correct interpreter. You can do that quickly by glancing at or mousing over the path that appears at the bottom right-hand corner of the PyCharm window -- it should display the path to the .venv folder in your project directory.

Word of Advice: If you've followed these steps and are having trouble -- especially if you've just installed everything and set up your project all in one go -- then you might want to reboot your computer, or at least try exiting and restarting PyCharm.

Run the command pip install shinybroker in your project's terminal.

You'll know it installed correctly and in the right place because you'll be able to find it in your .venv folder:

You need to check a few settings in TWS to make sure it will permit a data connection with ShinyBroker.

1. Launch TWS and sign in to your paper account (or use the demo)
2. Open the API Configuration menu found at File > Global Configuration > API > Settings.
3. Check Enable ActiveX and Socket Clients
4. Un-check Read-only API to allow ShinyBroker to send orders to TWS. We won't be using this in the current tutorial but subsequent articles will need it. Your settings menu should now look like the below:
   
5. Click "Apply" and "OK"
6. Don't close TWS. You'll need it open and running or else ShinyBroker won't have an IBKR connection to connect to!

1. Create a new Python script in PyCharm with File > New, then select "Python File" and give it an informative name (the example uses "hello_world_1.py").
2. Paste the code below into your script:

   
   import shinybroker as sb
   
   # Create an instance of a ShinyBroker App object using the default ui and server
   app = sb.sb_app(
       host='127.0.0.1',  # localhost TWS is being served on your local machine
       port=7497,         # make this match the port in your API Settings config
       client_id=10742    # picked at random, choose another Client ID if preferred
   )
   
   # Run the app
   app.run()

   Copy Code
3. Run your Python script. There are many ways to do so, but one quick and easy way is to highlight all of the code in your script with "select all", right-click the selection, and choose "Execute Selection in Python Console". It's even faster with keyboard shortcuts, e.g., for a Mac: command-A to select all, then alt-shift-E to execute. You can find those commands, and their shortcuts, by right-clicking on highlighted code in PyCharm.
4. After you execute the code PyCharm will launch a new Python console to run the code you told it to run. Your screen should look something like the below. You can see what the code you ran did: it created a ShinyBroker app object and told it where to find an IBKR connection by specifying host, port, and client_id. By itself, that app object does nothing but sit there in variable space; to make it run, you have to call its run method, which we did in the final line of the sample code when we called app.run(). That command is the one that started the continuously-running Python process that you see in your Console. That process serves your ShinyBroker app at the blue hyperlink appearing in the command line output. The app will continue to run until you tell it to stop (e.g., by clicking the red square in the Python Console in PyCharm).
   
5. To view your app, click the hyperlink in the command line output. Doing so will open your first ShinyBroker App in your default browser! You can also copy-paste the url into a browser of your choice. (And if you're thinking can I serve the app on one computer and access the app via browser from another computer/phone in a different location the answer is "yes, you can", but that's a later topic)

When you navigate a browser to the url at which your app is being served, you should be greeted with an app that looks something like the screen snip below.

Take a few minutes to poke around in the app and try out some of the default tabs & tools provided for tasks involving market data, contract matching, socket messages from IBKR, and so on.

Especially important to note is the section on the home page, which currently reads no ui passed to sb_ui(). That space is special -- it is reserved for you, the trader, to put UI elements and controls for your trading system. Since no ui was specified when we created this simple app object in this hello world example, ShinyBroker is telling you that it's empty.

We'll conclude this tutorial in the next step by injecting a little bit of ui into that space.

First, we'll need the two pieces of UI that will appear on the web page: an input for the user to type into, and an output to see the result. We'll use the input_text and output_code objects made available by the ui object in Shiny, and store them together in a div, with the input on top of the output. All sorts of different components are available both in Shiny and in other packages like shinywidgets, or you can build your own. In this example, however, we'll only need two components: input_text and output_code. In the code below we use these components to create a new piece of ui and assign to it the appropriate name a_piece_of_new_ui.

from shiny import ui

# Some UI to add to the app
a_piece_of_new_ui = ui.div(
    ui.input_text(
        id='sb_example_text_in',
        label='Example Input. Type something!'
    ),
    ui.output_code('sb_example_text_out')
)

Now we need some logic: a function that recognizes the input text box (which we named sb_example_text_in above) as an input that it needs to watch. It should also possess the additional properties such that, whenever the text in the input changes, the function executes, calculates the new string that we want for the text output, and sends that value to the output object that we named sb_example_text_out. ShinyBroker uses the Shiny framework (see the video above) to simplify all of the 'watching and updating' tasks in order to make it easy to write a function that does the job.

In Shiny-speak, what we want to write is called a rendering function, a special type of function that was created for exactly the kind of 'watching and updating' functionality that we need. A suitable rendering function is provided below but if you're new to Shiny, consider the following bullet points to help you understand rendering functions and why the code is written the way it is so that you can be better equipped to write your own.

• Shiny takes into consideration the names you give to your server functions and uses them to figure out where the return values should be passed. In most use cases, including the current tutorial, that's a lot simpler than it sounds because it boils down to: when you write your function, just give it the same name as the output you want it to update. That simple 'rule' will get you through 95% of your use cases. In our case, we want to update the output object named sb_example_text_out, so that's the name we'll assign to our function.
• We want the function to run every time the value of the input box sb_example_text_in changes, so somewhere within the function's body we'll need to call input.sb_example_text_in() to fetch the contents of the input box. Shiny handles the rest, which is extremely convenient because it allows you to treat input .sb_example_text_in() almost like a variable that you can always trust to contain "whatever is currently in the input box". Note that calling an input function to get its value carries with it a computational expense, so if you find yourself making calls to the same input more than once within the same render function, it's probably bad code. You're most likely better off if you just make the call once, store the input's value as a local variable, and then use that variable in the rest of your function code.
• Finally, we want to communicate to Shiny that our function is indeed a rendering function, which we can do by decorating it with a @render decorator. All sorts of render decorators are available, and of course you can write your own, but we'll be using @render.code so that the output text looks cool and monospaced-formatted like computer code. You can try stopping and re-running your app with other decorators like @render.text to see what happens with other sorts of decorators.

Taking all that into account, a render function that suits our purposes might look like the one below:

    @render.code
    def sb_example_text_out():
        return f"You entered '{input.sb_example_text_in()}'."

All that's left is to put that function into an app! Fortunately, ShinyBroker makes that easy. In practice, when making a real trading app, you will probably have tons of different functions required to make the app work, perhaps stored in different files, doing tasks like calculating your models, updating your charts, outputs, and so on. No matter how many you have, you can include all your functions in your app simply by wrapping them into one overall server function that you can pass to sb.sb_app() when you build your ShinyBroker app. It does not matter what you name your server function; the only requirement is that its signature contains the five parameters input: Inputs, output: Outputs, session: Session, ib_socket, sb_rvs. The part of your app that you, the the trader, will write will not always, or even usually, make use all five parameters explicitly, but they need to be there in your server function so that ShinyBroker can keep track of session information in its internals.

Below, we do exactly that: wrap the render function we just wrote into a new server function named a_server_function.

from shiny import Inputs, Outputs, Session, ui, render

# Server to support the new UI
# Signature must always contain the following five parameters:
#   input, output, session, ib_socket, and sb_rvs
def a_server_function(
        input: Inputs, output: Outputs, session: Session, ib_socket, sb_rvs
):
    @render.code
    def sb_example_text_out():
        return f"You entered '{input.sb_example_text_in()}'."

And finally... here comes the magic of ShinyBroker. We can create a new ShinyBroker app by passing our ui and server functions as arguments to sb_app:

import shinybroker as sb

# Create a ShinyBroker app with the new ui and server
app = sb.sb_app(
    a_piece_of_new_ui,
    a_server_function,
    host='127.0.0.1',
    port=7497,
    client_id=10742
)

And that's it! Altogether, the fully completed code example, including app.run(), can be found below:

import shinybroker as sb
from shiny import Inputs, Outputs, Session, ui, render


# Some UI to add to the app
a_piece_of_new_ui = ui.div(
    ui.input_text(
        id='sb_example_text_in',
        label='Example Input. Type something!'
    ),
    ui.output_code('sb_example_text_out')
)


# Server to support the new UI
# Signature must always contain the following five parameters:
#   input, output, session, ib_socket, and sb_rvs
def a_server_function(
        input: Inputs, output: Outputs, session: Session, ib_socket, sb_rvs
):
    @render.code
    def sb_example_text_out():
        return f"You entered '{input.sb_example_text_in()}'."


# Create a ShinyBroker app with the new ui and server
app = sb.sb_app(
    a_piece_of_new_ui,
    a_server_function,
    host='127.0.0.1',
    port=7497,
    client_id=10742
)

app.run()
                        

Run your app and view it in a browser like you did in Step 4. You should see something like the below in your Home tab, and the output should update with whatever you type into the input: