cap/cap.ipynb

{
    "metadata": {
        "cap_nb_version": "1.0.0",
        "cap_magic": "import os\nimport platform\nimport subprocess\nfrom threading import Thread\nfrom IPython import get_ipython\nfrom IPython.core.magic import (Magics, magics_class, cell_magic, line_magic)\n\nlist_thread_cmds = [\n    'cds watch',\n    'cf login'\n]\n\ndef start_thread_darwin(line):\n    list_thread_darwin = [\n        'printf \\\"#!/bin/bash',\n        'function finish {',\n        'rm notebook_thread.sh;'\n        '}',\n        'cd ' + os.getcwd(),\n        line,\n        'trap finish EXIT\\\" > notebook_thread.sh'\n    ]\n    thread_darwin = '\\\\n'.join(list_thread_darwin)\n    thread_darwin += ' && chmod +x notebook_thread.sh'\n    thread_darwin += ' && open -a Terminal notebook_thread.sh'\n    return thread_darwin\n\n\ndef get_system_info(platform, line):\n    system_info = { 'terminal': '', 'shell': '' }\n    if platform == 'Windows':\n        system_info['shell'] = 'cmd'\n        system_info['terminal'] = 'start cmd /c ' + line\n    elif platform == 'Linux':\n        system_info['shell'] = 'bash'\n        system_info['terminal'] = 'gnome-terminal -- ' + line\n    elif platform == 'Darwin':\n        system_info['shell'] = 'bash'\n        # Store in tmp folder\n        system_info['terminal'] = 'printf \\\"#!/bin/bash\\\\n' \\\n                                  'function finish {\\\\n' \\\n                                  'rm notebook_thread.sh;\\\\n' \\\n                                  '}\\\\n' \\\n                                  'cd ' + os.getcwd() + '\\\\n' + line + '\\\\n' \\\n                                  'trap finish EXIT\\\" > notebook_thread.sh' \\\n                                  ' && chmod +x notebook_thread.sh && open -a Terminal notebook_thread.sh'\n        'printf \\\"{{{shell}}}\\\" > notebook_thread.sh' \\\n                                  ' && chmod +x notebook_thread.sh' \\\n                                  ' && open -a Terminal notebook_thread.sh'\n    return system_info\n\n@magics_class\nclass CustomMagics(Magics):\n\n    # Modified %lsmagic to show up in vscode's notebook extension\n    @line_magic\n    def listmagic(self, line):\n        line = line.strip()\n        magics = str(get_ipython().run_line_magic('lsmagic', '',  _stack_depth=2))\n        magics = magics.replace('\\n', ' ')\n        return magics\n\n    # Helper function to also be able to replace variables when writing files\n    @cell_magic\n    def writetemplate(self, line, cell):\n        \"Writes file while inserting environment variables given as {var}\"\n        replaced = []\n        filepath = line.strip('\"')\n        with open(filepath, 'w', encoding='utf8') as f:\n            for k, v in sorted(os.environ.items()):\n                template = '{' + k + '}'\n                if '{' not in v:\n                    template_value = '\"' + v + '\"'\n                else:\n                    template_value = v\n                if template in cell:\n                    cell = cell.replace(template, template_value)\n                    replaced.append('{' + k + '}=' + template_value)\n            f.write(cell)\n        return 'Replaced ' + ', '.join(replaced) + '. Writing ' + line + '.'\n\nget_ipython().register_magics(CustomMagics)\n\ndef new_thread_window(line):\n    \"Runs cds with native CLI, with function 'cds watch' being executed as a separate thread in new a terminal window.\"\n    line = line.strip()\n    system_info = get_system_info(platform.system(), line)\n    cell_magic = system_info['terminal']\n    # Starts a separate thread such that cmd does not block the notebook\n    if cell_magic:\n        def do_magic():\n            get_ipython().run_cell_magic(system_info['shell'], '', cell_magic)\n        Thread(target=do_magic).start()\n        return 'Running ' + line + '...'\n    else:\n        return 'Please open a new terminal outside of the notebook and run: ' + line + '...'\n\ndef filter(*args):\n    cmd = ' '.join(list(args))\n    if cmd.lower().startswith(tuple(list_thread_cmds)):\n        new_thread_window(cmd)\n        print(cmd + ' started in new terminal window')\n    else:\n        cmd = ' '.join(list(args))\n        try:\n            output = subprocess.check_output(cmd, shell=True, stderr=subprocess.STDOUT)\n            for line in output.splitlines():\n                print(line.decode('utf-8'))\n        except subprocess.CalledProcessError as e:\n            for line in e.output.splitlines():\n                if line.startswith(b'[ERROR]'):\n                    print('\\n')\n                print(line.decode('utf-8'))\n    return\n\nget_ipython().system = filter",
        "language_info": {
            "codemirror_mode": {
                "name": "ipython",
                "version": 3
            },
            "file_extension": ".py",
            "mimetype": "text/x-python",
            "name": "python",
            "nbconvert_exporter": "python",
            "pygments_lexer": "ipython3",
            "version": 3
        },
        "orig_nbformat": 2
    },
    "nbformat": 4,
    "nbformat_minor": 2,
    "cells": [
        {
            "cell_type": "markdown",
            "metadata": {},
            "source": [
                "<h1>Welcome to CAP Notebooks!&emsp;<img style=\"vertical-align:middle\" src=\"https://cap.cloud.sap/docs/assets/logos/sap.svg\" alt=\"drawing\" width=\"70\"/><img style=\"vertical-align:middle\" src=\"https://cap.cloud.sap/docs/assets/logos/cap.svg\" alt=\"drawing\" width=\"60\"/></h1>\n",
                "\n",
                "## What is a CAP Notebook?\n",
                "\n",
                "A CAP notebook is a [Jupyter Notebook](https://jupyter.org/) that serves as a guide on how to create, navigate and monitor CAP projects.\n",
                "\n",
                "With this, we want to encourage the CAP community to work with CAP in the same *explorative* manner that data scientists work with their data by:\n",
                "\n",
                "- Visually interacting with their code\n",
                "- Playing with REPL-type inputs (notebook input cells)\n",
                "- Storing persistent code (notebook output cells)\n",
                "\n",
                "The cell inputs/outputs are especially useful at later points in time when the project's details have long been forgotten. In addition, notebooks are a good way to share, compare and also reproduce projects.\n",
                "<br><br>\n",
                "\n",
                "## How do I run the CAP Notebook?\n",
                "\n",
                "The following symbols indicate the state of a cell:\n",
                "\n",
                "&emsp;&emsp;&emsp;  `▶` : Executes the cell\n",
                "\n",
                "&emsp;&emsp;&emsp;  `*`   : Indicates that the cell is *running*\n",
                "  \n",
                "&emsp;&emsp;&emsp;  `■`   : Stops cell execution\n",
                "\n",
                "When finished running, you will see the cell's output appear below the code cell. The blue bar on the left moves to keep track of where you are in the notebook. You can use `+` to add new cells anywhere in the notebook. See [Guide](https://code.visualstudio.com/docs/python/jupyter-support#_create-or-open-a-jupyter-notebook) for a more detailed description.\n",
                "<br><br>\n",
                "\n",
                "## How do I interact with the CAP Notebook?\n",
                "\n",
                "In notebooks, predefined [Magic commands](https://ipython.readthedocs.io/en/stable/interactive/magics.html) have been designed to succinctly solve various common problems. They all start with `%` or `%%` for line or cell magic commands.\n",
                "\n",
                "&emsp;&emsp;&emsp; `%quickref`  : Provides a full list of magic functions available\n",
                "\n",
                "You will find these being used throughout the notebook.\n",
                "<br><br>\n",
                "\n",
                "## How do I get started?\n",
                "\n",
                "Start by executing the first cell, which registers some additional magic commands which make our notebook platform-independent (across Windows, Linux and Mac).\n",
                "\n",
                "After that, you're ready to start the CAP [Getting started in a Nutshell](https://cap.cloud.sap/docs/get-started/in-a-nutshell) tutorial. \n",
                "\n",
                "**```🡇 NOTE: This cell must be included and run at the start of any CAP Notebook! 🡇```**"
            ]
        },
        {
            "cell_type": "code",
            "execution_count": null,
            "metadata": {
                "tags": []
            },
            "outputs": [],
            "source": [
                "import glob, json\n",
                "with open(glob.glob('./*.ipynb')[0], encoding='utf8') as json_file:\n",
                "    exec(json.load(json_file)['metadata']['cap_magic'])"
            ]
        },
        {
            "cell_type": "markdown",
            "metadata": {},
            "source": [
                "# Getting Started in a Nutshell\n## Using a minimalistic setup\n\n\nGet started in a minimalistic setup with *[Node.js](https://nodejs.org)*, *[express](http://expressjs.com)* and *[SQLite](http://sqlite.org)*.\n\n See also: *[Java-based variant of this guide](https://cap.cloud.sap/docs/java/getting-started)*.\n\n\n\n\n\n\n## Jumpstarting Projects<a id=\"start-a-project\"></a>\n\n\n[After installing `@sap/cds-dk` globally](https://cap.cloud.sap/docs/get-started/#local-setup), `cds init` has already created a project with minimal defaults for us.\n\n### Launch `cds watch`\n\n\nFor an automated jumpstart, you can just tell `cds` to watch out for things to arrive:\n\n"
            ]
        },
        {
            "cell_type": "code",
            "execution_count": null,
            "metadata": {},
            "outputs": [],
            "source": [
                "!cds watch"
            ]
        },
        {
            "cell_type": "markdown",
            "metadata": {},
            "source": [
                "Use `cds watch` to start a cds server, even in a newly created and yet empty project. Whenever you feed your project with new content, for example, by adding or modifying `.cds`, `.json`, or `.js` files, the server automatically restarts to serve the new content. Because there isn’t any content in your project yet, it just keeps waiting with a message like this:\n\n<pre><code>\n[cds] - running nodemon...\n--ext cds,csn,csv,ts,mjs,cjs,js,json,properties,edmx,xml\n\n    No models found at db/,srv/,app/,schema,services,.\n    Waiting for some to arrive...\n\n</pre></code>\n\n\n## Defining Domain Models<a id=\"domain-models\"></a>\n\n\n\nLet’s feed our project by adding a simple domain model. Start by creating a file named `db/schema.cds` (also indicated in the code box’s label) and copy the following definitions into it:"
            ]
        },
        {
            "cell_type": "code",
            "execution_count": null,
            "metadata": {},
            "outputs": [],
            "source": [
                "%%writefile \"db/schema.cds\"\n\nusing { Currency, managed, sap } from '@sap/cds/common';\nnamespace sap.capire.bookshop;\n\nentity Books : managed {\n  key ID : Integer;\n  title  : localized String(111);\n  descr  : localized String(1111);\n  author : Association to Authors;\n  genre  : Association to Genres;\n  stock  : Integer;\n  price  : Decimal(9,2);\n  currency : Currency;\n}\n\nentity Authors : managed {\n  key ID : Integer;\n  name   : String(111);\n  books  : Association to many Books on books.author = $self;\n}\n\n/** Hierarchically organized Code List for Genres */\nentity Genres : sap.common.CodeList {\n  key ID   : Integer;\n  parent   : Association to Genres;\n  children : Composition of many Genres on children.parent = $self;\n}"
            ]
        },
        {
            "cell_type": "markdown",
            "metadata": {},
            "source": [
                "⮡   [Find this source also in **cap/samples**](https://github.com/sap-samples/cloud-cap-samples/tree/master/bookshop/db/schema.cds)\n\n\n\n  ⮡   [Learn more about **Domain Modeling**](https://cap.cloud.sap/docs/guides/domain-models)\n\n\n\n  ⮡   [Learn more about **CDS Modeling Languages**](https://cap.cloud.sap/docs/cds)\n\n\n\n### Deployed to Databases Automatically\n\n\nAs soon as you save your file, the still running `cds watch` will react immediately with new output like this:\n\n<pre><code>\n[cds] - connect to db { database: *':memory:'* }\n/> successfully deployed to sqlite in-memory db\n</pre></code>\n\n\nThis means that `cds watch` detected the changes in `db/schema.cds` and automatically bootstrapped an in-memory SQLite database when restarting the server process.\n\n\n  ⮡   [Learn more about using databases below](https://cap.cloud.sap/docs/get-started/in-a-nutshell#databases)\n\n\n\n\n\n## Defining Services<a id=\"defining-services\"></a>\n\n\n\nAfter the recent changes, `cds watch` also prints this message:\n\n<pre><code>\n    No service definitions found in loaded models.\n    Waiting for some to be added...\n</pre></code>\n\n\nSo, let’s go on feeding it with service definitions.\nFollowing the [best practice of single-purposed services](https://cap.cloud.sap/docs/guides/services#single-purposed-services), we’ll define two services for different use cases.\n\n### One for Admins to Maintain *Books* and *Authors*\n"
            ]
        },
        {
            "cell_type": "code",
            "execution_count": null,
            "metadata": {},
            "outputs": [],
            "source": [
                "%%writefile \"srv/admin-service.cds\"\n\nusing { sap.capire.bookshop as my } from '../db/schema';\nservice AdminService @(_requires:'authenticated-user') {\n  entity Books as projection on my.Books;\n  entity Authors as projection on my.Authors;\n}"
            ]
        },
        {
            "cell_type": "markdown",
            "metadata": {},
            "source": [
                "⮡   [Find this source also in **cap/samples**](https://github.com/sap-samples/cloud-cap-samples/tree/master/bookshop/srv/admin-service.cds)\n\n\n\n### And One for End Users to Browse and Order *Books*\n"
            ]
        },
        {
            "cell_type": "code",
            "execution_count": null,
            "metadata": {},
            "outputs": [],
            "source": [
                "%%writefile \"srv/cat-service.cds\"\n\nusing { sap.capire.bookshop as my } from '../db/schema';\nservice CatalogService @(path:'/browse') {\n\n  @readonly entity Books as SELECT from my.Books {*,\n    author.name as author\n  } excluding { createdBy, modifiedBy };\n\n  @requires_: 'authenticated-user'\n  action submitOrder (book: Books:ID, amount: Integer);\n}"
            ]
        },
        {
            "cell_type": "markdown",
            "metadata": {},
            "source": [
                "⮡   [Find this source also in **cap/samples**](https://github.com/sap-samples/cloud-cap-samples/tree/master/bookshop/srv/cat-service.cds)\n\n\n\n  ⮡   [Learn more about **Defining Services**](https://cap.cloud.sap/docs/guides/services)\n\n\n\n### Served to OData out-of-the-box\n\n\nThis time `cds watch` reacted with additional output like this:\n\n<pre><code>\n[cds] - serving AdminService { at: *'/admin'* }\n[cds] - serving CatalogService { at: *'/browse'*, impl: *'bookshop/srv/cat-service.js'* }\n[cds] - launched in: 744.291ms\n[cds] - server listening on { url: *'http://localhost:4004'* }\n</pre></code>\n\n\nAs you can see in the log output, the two service definitions have been compiled and generic service providers have been constructed to serve requests on the listed endpoints `/admin` and `/browse`.\n\nOpen *[http://localhost:4004](http://localhost:4004)* in your browser and see the generic `index.html` page:\n\n"
            ]
        },
        {
            "cell_type": "code",
            "execution_count": null,
            "metadata": {},
            "outputs": [],
            "source": [
                "%%html\n<iframe src='http://localhost:4004' width=1000 height=600 style='background-color:white'></iframe>"
            ]
        },
        {
            "cell_type": "markdown",
            "metadata": {},
            "source": [
                "## Using Databases<a id=\"databases\"></a>\n\n\n### Using *sqlite* In-Memory Database\n\n\nAs [previously shown](https://cap.cloud.sap/docs/get-started/in-a-nutshell#deployed-in-memory), `cds watch` automatically bootstraps an SQLite in-process and in-memory database by default — that is, unless told otherwise. While this **isn’t meant for productive use**, it drastically speeds up development turn-around times, essentially by mocking your target database, for example, SAP HANA.\n\n\n  ⮡   [Learn more about mocking options in **Grow as you go**](https://cap.cloud.sap/docs/get-started/grow-as-you-go)\n\n\n\n### Adding Initial Data in `.csv` Files\n\n\nNow, let’s fill your database with initial data by adding a few plain CSV files under `db/data` like this:"
            ]
        },
        {
            "cell_type": "code",
            "execution_count": null,
            "metadata": {},
            "outputs": [],
            "source": [
                "%cd db\n%mkdir data\n%cd .."
            ]
        },
        {
            "cell_type": "code",
            "execution_count": null,
            "metadata": {},
            "outputs": [],
            "source": [
                "%%writefile \"db/data/sap.capire.bookshop-Books.csv\"\n\nID;title;author_ID;stock\n201;Wuthering Heights;101;12\n207;Jane Eyre;107;11\n251;The Raven;150;333\n252;Eleonora;150;555\n271;Catweazle;170;22"
            ]
        },
        {
            "cell_type": "code",
            "execution_count": null,
            "metadata": {},
            "outputs": [],
            "source": [
                "%%writefile \"db/data/sap.capire.bookshop-Authors.csv\"\n\nID;name\n101;Emily Brontë\n107;Charlotte Brontë\n150;Edgar Allen Poe\n170;Richard Carpenter"
            ]
        },
        {
            "cell_type": "markdown",
            "metadata": {},
            "source": [
                "⮡   [Find a full set of `.csv` files in **cap/samples**](https://github.com/sap-samples/cloud-cap-samples/tree/master/bookshop/db/data)\n\n\n\n\n\nAfter you’ve added these files, `cds watch` restarts the server with output, telling us that the files have been detected and their content been loaded into the database automatically:\n\n<pre><code>\n[cds] - connect to db { database: *':memory:'* }\n > filling sap.capire.bookshop.Authors from bookshop/db/data/sap.capire.bookshop-Authors.csv\n > filling sap.capire.bookshop.Books from bookshop/db/data/sap.capire.bookshop-Books.csv\n/> successfully deployed to sqlite in-memory db\n</pre></code>\n> This is the output when you’re using the [samples](https://github.com/sap-samples/cloud-cap-samples). It’s less if you’ve followed the manual steps here.\n\n\n\n\n  ⮡   [Learn more about **Using Databases**](https://cap.cloud.sap/docs/guides/databases)\n\n\n\n### Querying Through OData out-of-the-box\n\n\nNow that we’ve a connected, fully capable SQL database, filled with some initial data, we can send complex OData queries, served by the built-in generic providers:\n\n\n  \n- *[browse/Books?\\$select=ID,title](http://localhost:4004/browse/Books?\\$select=ID,title)*\n\n  \n- *[admin/Authors?\\$search=Bro](http://localhost:4004/admin/Authors?\\$search=Bro)*\n\n  \n- *[admin/Authors?\\$expand=books(\\$select=ID,title)](http://localhost:4004/admin/Authors?\\$expand=books(\\$select=ID,title))*\n\n\n\n\n  ⮡   [Learn more about **Generic Providers**](https://cap.cloud.sap/docs/guides/generic)\n\n\n\n  ⮡   [Learn more about **OData’s Query Options**](https://cap.cloud.sap/docs/advanced/odata)\n\n\n\n\n\n## Summary and Next Steps…<a id=\"summary-and-next-steps\"></a>\n\n\n\n\n[**Visit our Cookbook**](https://cap.cloud.sap/docs/guides/) to find more task-oriented guides. For example, you can find guides about potential next steps such as adding [Authentication](https://cap.cloud.sap/docs/node.js/authentication) and [Authorization](https://cap.cloud.sap/docs/guides/authorization) or [Deploying to Cloud Foundry](https://cap.cloud.sap/docs/advanced/deploy-to-cloud).\n\nAlso **see the reference sections** to find detailed documentation about [**CDS**](https://cap.cloud.sap/docs/cds), as well as [**Node.js**](https://cap.cloud.sap/docs/node.js) and [**Java**](https://cap.cloud.sap/docs/java) Service SDKs and runtimes."
            ]
        }
    ]
}