Meta tags:
author=Nirum team;

Headings (most frequently used words):

step, interface, by, tutorial, what, nirum, is, for, installing, compiler, service, compiling, filling, with, implementation, remote, procedure, call, method, parameters, server, side, unit, tests, further, reading,

Text of the page (most frequently used words):
the (196), counter (77), python (65), nirum (64), and (62), you (37), self (35), increment (34), state (34), that (34), can (33), with (29), http (29), package (28), like (28), #server (28), service (28), name (26), this (25), from (23), for (23), interface (22), are (22), method (20), language (20), not (18), need (17), code (16), implementation (16), target (15), also (15), tests (15), file (15), has (15), import (15), schema (15), type (15), directory (15), command (14), path (14), unit (14), def (14), client (14), out (14), only (13), delta (13), files (13), compiler (13), tutorial (12), have (12), above (12), which (12), pip (12), what (11), class (11), how (11), counter_client (11), venv (11), foo (11), counterimpl (10), source (10), post (10), 9322 (10), int (10), any (10), version (10), but (10), __init__ (10), src (10), setup (9), microservice (9), transport (9), state_path (9), does (9), environment (9), bar (9), following (8), its (8), because (8), install (8), more (8), call (8), argument (8), time (8), json (7), counter_server (7), write (7), work (7), well (7), count (7), return (7), bigint (7), example (7), other (7), there (7), types (7), all (7), virtual (7), activate (7), toml (7), two (7), greet (7), annotations (6), try (6), below (6), string (6), since (6), testing (6), named (6), built (6), than (6), curl (6), 123 (6), would (6), changed (6), means (6), request (6), now (6), one (6), wsgi (6), generated (6), nrm (6), used (6), let (6), pyvenv (6), windows (6), step (6), serialization (5), become (5), methods (5), instead (5), make (5), don (5), most (5), assertequal (5), details (5), microservices (5), both (5), data (5), httptransport (5), str (5), option (5), resource (5), parameter (5), about (5), making (5), way (5), result (5), may (5), number (5), into (5), makes (5), run (5), corresponding (5), even (5), single (5), using (5), every (5), becomes (5), text (5), reading (4), doesn (4), takes (4), integer (4), after (4), library (4), languages (4), although (4), much (4), why (4), side (4), open (4), parameters (4), tmp (4), debugger (4), notice (4), line (4), calls (4), content (4), them (4), compile (4), look (4), through (4), official (4), between (4), python3 (4), check (4), installed (4), your (4), pep (4), translated (4), field (4), contains (4), pypi (4), targets (4), written (4), decimal (4), arguments (4), public (4), nonnull (4), function (4), compatible (3), further (3), unittest (3), rest (3), test (3), instance (3), under (3), hood (3), then (3), necessary (3), defined (3), such (3), level (3), traditional (3), idl (3), programming (3), again (3), reloads (3), except (3), annotation (3), possible (3), was (3), guess (3), implies (3), application (3), observe (3), restarting (3), stat (3), bin (3), process (3), will (3), none (3), response (3), current (3), save (3), vary (3), options (3), url (3), output (3), dir (3), platforms (3), provides (3), these (3), protocol (3), simple (3), easily (3), use (3), least (3), works (3), going (3), later (3), port (3), consists (3), remote (3), omitted (3), shell (3), project (3), made (3), actual (3), py2 (3), manifest (3), looks (3), minimal (3), foo_bar (3), hyphens (3), underscores (3), purpose (3), cases (3), java (3), defines (3), define (3), notimplementederror (3), description (3), point (3), examples (3), values (3), null (3), greetservice (3), backward (2), refactoring (2), format (2), few (2), features (2), see (2), resources (2), runs (2), quite (2), malformed (2), test_increment_by_5 (2), test_increment (2), test_initial_state (2), constructor (2), store (2), teardown (2), standard (2), mkstemp (2), testcase (2), shows (2), low (2), libraries (2), hides (2), user (2), complicated (2), functional (2), deal (2), ignore (2), network (2), transportation (2), coding (2), nirum_http (2), touched (2), read (2), filenotfounderror (2), recompile (2), corresponds (2), same (2), chapter (2), previous (2), could (2), persistent (2), haven (2), running (2), press (2), ctrl (2), quit (2), active (2), pin (2), 456 (2), 789 (2), add (2), expression (2), change (2), reloading (2), traceback (2), required (2), starts (2), 200 (2), length (2), origin (2), access (2), control (2), allow (2), better (2), they (2), runtime (2), route (2), many (2), indeed (2), top (2), dumb (2), nevertheless (2), writing (2), however (2), objects (2), true (2), implements (2), here (2), first (2), needs (2), explained (2), module (2), itself (2), given (2), activated (2), procedure (2), without (2), everytime (2), editable (2), packages (2), own (2), returns (2), implement (2), utilize (2), interactive (2), system (2), docs (2), creating (2), scripts (2), bat (2), prompt (2), once (2), cetera (2), exe (2), aware (2), before (2), mostly (2), created (2), fill (2), article (2), assumes (2), higher (2), though (2), wonder (2), tree (2), hints (2), typing (2), cannot (2), okay (2), indistinguishable (2), names (2), latin (2), alphabets (2), rule (2), naming (2), been (2), purposes (2), lowercase (2), when (2), pascalcase (2), right (2), sum (2), several (2), things (2), raise (2), compiled (2), complete (2), merely (2), major (2), packaging (2), must (2), configures (2), shorten (2), generates (2), interfaces (2), submitted (2), uninstall (2), https (2), useless (2), order (2), section (2), suffix (2), correspond (2), floating (2), signed (2), arbitrary (2), note (2), logic (2), world (2), hello (2), general (2), covers, interested, ran, 004s, satisfies, behaviors, expect, straightforward, concise, payload, tries, fixture, creates, temporary, removes, finish, uses, framework, friendly, derives, xunit, tempfile, counterimpltest, close, unlink, where, whereas, hidden, usually, still, adopted, hide, networking, fortunately, our, less, painful, facing, app, somewhat, analogous, respect, calling, conventions, wouldn, stdcall, cdecl, 249, expected, 126, variable, component, appended, typed, slighly, evolves, previously, designed, minimize, complexity, intention, familiar, web, development, adapter, taking, cat, detected, recent, last, typeerror, missing, positional, unexpectedly, terminated, properly, concurrent, please, seek, fix, saved, think, strange, filesystem, database, memory, countimpl, slightly, replaces, existing, anew, reload, updated, shorthand, per, meaning, discovered, backends, processed, scans, fancy, paths, surface, urls, typical, apis, feature, enabled, adopts, widely, standards, regardless, inefficiency, goals, interoperate, systems, efficiency, non, goal, priority, old, fashioned, anyway, nicely, called, lot, simulate, communicate, despite, realized, soon, useful, interesting, relationship, isinstance, issubclass, fun, fact, too, actually, demo, session, address, communication, intended, agents, small, followed, colon, evaluated, turns, debug, mode, related, changes, ensure, modified, debian, ubuntu, besides, counts, just, increments, finally, ready, smallest, working, activating, global, environments, indication, platform, while, executed, starting, cfg, include, lib, depending, configured, probably, already, unless, known, thought, workspace, interpreter, settings, third, party, dependencies, new, mkdir, trees, getting, involved, place, hierarchy, implementing, keep, assuming, recommend, filling, generate, aggressively, annotates, leverage, typeness, hint, introduced, removing, modern, 484, 483, 3107, syntax, suggested, style, divide, words, continuous, neither, nor, disallowed, foo_, each, insensitive, equivalent, start, consist, arabic, digits, detailed, portable, very, limited, sure, seems, kind, correspondence, discussed, mentioned, explicit, facto, raising, common, practice, community, hand, left, truth, snake_case, foobar, classes, object, unfortunately, human, readable, machines, remove, extrinsic, reformat, scan, gist, installer, clone, ported, distinction, versions, automatically, switches, pack, tagged, wheels, 425, whl, wheel, tools, recognize, setuptools, refers, were, exist, yet, broken, down, compiling, mean, builds, should, done, whichever, private, configure, set, appeared, org, case, wait, decided, choose, mature, moment, end, numbers, mapped, float, real, float64, float32, int64, int32, keyword, definition, follows, precision, had, parentheses, empty, show, elementary, supposes, artificial, natural, zero, get, incremented, long, story, short, invokes, indicates, consistent, within, placed, directories, appropriate, permissions, downloaded, binary, linux, macos, prebuilt, executable, binaries, three, stable, 2018, releases, page, installing, illustrates, steps, unnecessary, decoupling, implementations, easier, enjoyable, focus, pure, concrete, enumerate, corner, mock, simpler, assumptions, present, proper, timestamp, enough, defining, record, datetime, iso, 8601, reduces, amount, error, handling, average, points, cover, reduced, large, extent, helps, architecture, achieved, robust, reasons, receiving, deserialization, validation, errors, optional, guaranteed, validated, greetservice_client, greetserviceimpl, remain, body, imagine, alternatively, stub, stands, signatures, procedures, today, live, age, replaced, multiple, anymore, serialize, await, parse, validate, allowed, range, definitions, hundreds, input, uncommon, turn, fyi, git, repository, codes, github, com, lang, estimated, exercising, hour, core, contirubtion, guide, changelog,

Text of the page (random words):
make an http request await a response from the server parse the response and validate the result if it is in the allowed range function definitions become even more complicated than function calls you need to make a server how about unit tests hundreds of test cases about malformed json input data are not uncommon unit tests easily turn indistinguishable from functional tests nirum is both an idl which stands for interface description language and the compiler implementation of the language at a time the language purposes to define signatures of remote procedures and data types used for parameters and return values the point is that it defines only an interface an implementation for it is written in a general purpose language like python the interface code looks like the following service greet service text greet text name the compiler takes an interface written in nirum language and generates a stub code for the implementation in a general purpose language if the target language is python it looks like the following code class greetservice def greet name str str raise notimplementederror alternatively it could be java public interface greetservice nonnull public string greet nonnull string name all that remain are to fill the body of greet with actual implementation and to call the function let us imagine that an implementation is like the following java code public class greetserviceimpl implements greetservice nonnull public string greet nonnull string name don t have to check name null here return hello name how is it like to call from a client code let s try with a python interactive shell run python command without any arguments c greetservice_client c greet world hello world that s all all other things like making an http request serialization receiving a request deserialization data validation and making errors don t have to be written by you but are generated by the compiler note that the name argument in the above implementation code does not check if it is null since the parameter type is not defined as an optional type i e text name instead of text name it is guaranteed not null argument values are validated first to sum up nirum helps microservices architecture to be easily achieved and robust for the following reasons it hides implementation details of transportation and data coding not only it reduces the amount of the code you need to write it does more like better error handling than average microservices the points you need to cover with unit tests are also reduced to a large extent it makes much simpler assumptions about arguments and return values the code you write doesn t need to check if any required field is present or it s a proper iso 8601 timestamp string but is enough by only defining a record type or typing a parameter as a datetime mock objects become unnecessary by decoupling interfaces from implementations and it means writing unit tests become much easier and enjoyable and you can focus to the pure logic so that you become to write concrete examples and enumerate much more corner cases of the logic the rest of this article illustrates how you can utilize nirum for your microservices through the steps by examples installing compiler the nirum compiler works on the most major platforms like linux macos and windows the official releases page provides the prebuilt executable binaries for these three platforms note that there is no stable version i e v1 0 0 or higher as of may 2018 this tutorial assumes that you have downloaded the right binary for your system named it nirum given it appropriate permissions e g x and placed it in one of your path directories so that nirum in the command line invokes the compiler indicates a command line prompt and it s consistent within this tutorial nirum v 0 5 0 service interface in order to show the elementary features of nirum this section supposes a simple artificial example a counter it has a state of a natural number and the state starts with zero client code can increment the state by 1 and get the current state after incremented at a time long story short it s merely like a microservice version of state how does the interface of the counter service look like service counter bigint increment a service keyword in the above code is for a service definition and counter which follows is the name of the service it has one method named increment which takes no arguments and returns an arbitrary precision integer that s what bigint means if it had any parameters it would be between the parentheses but it s empty in the above method there are other built in number types as well two signed integer types int32 int64 two signed floating point number types float32 float64 and an arbitrary real number type decimal in python all built in integer types correspond to int and floating point numbers correspond to float the decimal is mapped to decimal decimal save this as a file named counter nrm nirum source files end with the suffix nrm to make the compiler compile an interface to a target language a source tree need to be a nirum package a minimal example of nirum package look like the below directory package toml counter nrm every nirum package has its own package toml manifest as the suffix implies it is written in toml version 1 0 0 description a useless counter service wait have we decided what language we target to in this tutorial we choose python as a target language because it s the most mature target language of the nirum compiler at this moment in order to add a target language we need a corresponding targets language section as well in case of python it s targets python version 1 0 0 description a useless counter service targets python name counter schema what does targets python name field mean not only the compiler builds a single python source file but it generates a python package which consists of python source files that define interfaces and setup py file so a python package can be installed and should be done with pip and also can be submitted to pypi whichever it s official or private if we configure name counter schema the name field of setup py file is set to counter schema so that you can uninstall it by pip uninstall counter schema command after you ve installed it the name also can be appeared in the url of the package on pypi e g https pypi python org pypi counter schema if it s submitted compiling now we have the most minimal nirum package that can be compiled let s compile it to a corresponding python package nirum target python output dir out the above command can be broken down into two options and an argument target python it configures the language we target to python and can be shorten as t python output dir out it configures a path of the directory that the generated python files go into it is okay even if out directory does not exist yet the compiler makes a directory if necessary it can be shorten as o out it refers to a directory that contains the nirum package we are going to compile it must be a directory that contains package toml at least in the above example it means there must be package toml file if it were src instead of there would have to be src package toml file as a result several files are made in the out directory out manifest in setup py src counter __init__ py src py2 counter __init__ py two text files in the top level are for python packaging python packaging tools like pip and setuptools recognize them the src directory contains the actual python source files you can observe that counter nrm file we made corresponds to counter __init__ py file the src py2 directory is merely a clone of src except it s ported to python 2 7 1 as its name implies you don t have to be aware of the distinction of two major python versions setup py automatically switches between them even if you pack wheel files i e whl two version tagged wheels are created further reading pep 425 as you can guess the out directory itself is a complete python package which can be installed using pip installer so how was counter counter service compiled in python although we can look at the generated out src counter __init__ py source file unfortunately it s not that human readable because it s only for machines nevertheless we can remove extrinsic details from it and reformat the code to scan its gist it s like the below from nirum service import service from nirum transport import transport class counter service def increment self int raise notimplementederror counter has to implement increment class counter_client counter the client object of class counter def __init__ self transport transport none def increment self int to sum up it defines two classes counter and counter_client we can guess several things from this the name in lowercase counter is translated to a pascalcase name counter that s right every type name becomes a pascalcase when it s translated to a python class e g foo bar becomes foobar on the other hand the method name in lowercase increment is left as it was increment the truth is that every name other than type name i e name of method parameter field becomes a snake_case when it s translated a python name e g foo bar becomes foo_bar since python doesn t have any explicit interface type like java interface the de facto interface type counter defines its methods raising notimplementederror indeed it is the common practice to define an interface in python community as mentioned in the above we can observe that bigint is translated to int in python there is also a built in implementation of counter counter_client we are not sure what it purposes but it seems like a kind of a client side correspondence of counter it will be discussed later in this tutorial since the detailed rule of naming in the nirum language has not been explained you may wonder about this to be mostly portable and compatible with many programming languages it has the very limited naming rule names can consist of latin alphabets arabic digits hyphens and underscores names can start with only latin alphabets cases are insensitive e g foo foo and foo are all equivalent hyphens and underscores are indistinguishable each other e g foo bar and foo_bar are the same hyphens and underscores only purpose to divide words they cannot be continuous more than once e g foo bar is okay but neither foo bar nor foo_ bar is disallowed even though you can code a name with foo bar foo bar or foo_bar the suggested style is foo bar 1 wonder why the compiler does not generate a single python source tree that works on both python 3 and 2 7 because the nirum compiler aggressively annotates type hints using the standard typing module to leverage nirum idl s well typeness as the annotation syntax used by type hint annotations is introduced since python 3 we need to port the result code to python 2 by removing these type annotations further reading for modern python type hints pep 3107 pep 483 and pep 484 filling interface with implementation before implementing the increment method we need to setup a minimal environment for programming python in this tutorial we re going to keep assuming we use python 3 4 2 or higher recommend python 3 6 though also as more source trees are getting involved this article assumes you place nirum package files in the above into counter schema directory so it looks like the following hierarchy counter schema package toml counter nrm out manifest in setup py src counter __init__ py src py2 counter __init__ py it s time to fill the interface we made in the above with an actual implementation in this chapter we work on counter server an other directory mkdir counter server cd counter server although you probably are already aware unless you haven t used python before mostly every python project need a corresponding virtual environment also known as venv you can thought it as a project workspace it consists of interpreter settings e g python version to use and third party dependencies a new virtual environment can be created using pyvenv command pyvenv venv as a result it makes a directory named venv configured through the argument of pyvenv command counter server venv bin or scripts on windows activate or activate bat on windows python or python exe on windows pip or pip exe on windows et cetera lib python3 6 depending on your python version omitted et cetera include omitted pyvenv cfg while creating a virtual environment has to be executed only once you need to activate it everytime you re starting to work on the project venv bin activate venv notice a venv indication in the above prompt it shows that you ve activated the virtual environment a way to activate a virtual environment may vary on the platform or the shell for example if you re on windows the way to activate it is like the below c counter server venv scripts activate bat see also creating virtual environments on the official docs of pyvenv for details after activating the environment pip becomes to install python packages in the environment not the system global let s install the python package we generated in the above 3 pip install editable counter schema out you can utilize the python interactive shell to check if the package is installed well import counter counter finally it s ready to implement the method the possible smallest working implementation would be like the below from counter import counter class counterimpl counter def __init__ self none self state 0 def increment self int self state 1 return self state what a dumb implementation it has its own state which counts from 0 the increment method just increments the state by 1 and returns the current state save the below python code to counter_server py to try to run now counter server directory has more files counter server venv omitted counter_server py 2 because it is the least python version with built in both pip and pyvenv if you re on debian ubuntu you need to install python3 pip and python3 venv packages besides python3 package 3 notice editable e option without this option you need to install the package again everytime any files in counter schema out are modified remote procedure call it s time to run the implementation to run it on the server we need nirum wsgi package 4 ensure that you ve activated the virtual environment pip install nirum wsgi this package provides the nirum server command which runs a server of a given nirum service nirum server d counter_server counterimpl running on http 0 0 0 0 9322 press ctrl c to quit restarting with stat debugger is active debugger pin 123 456 789 the d option turns on debug mode which means the server reloads every time any of related files changes the argument of nirum service command is a small language that consists of an import path i e python module path followed by a colon and a following python expression evaluated to a nirum service instance not a class itself notice the address http 0 0 0 0 9322 you can change the port using p port option the protocol used for communicat...