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):
ated 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 communication between a service server and a service client is http and it s intended to be also possible to be used with any http user agents it will be more explained in a later however first of all let s try a counter_client generated by the compiler as a server side needs nirum wsgi package a client side needs nirum http package pip install nirum http here s a demo session from counter import counter_client from nirum_http import httptransport transport httptransport http 0 0 0 0 9322 client counter_client transport client increment 1 client increment 2 client increment 3 one fun fact is that counter_client too actually implements counter interface from counter import counter isinstance client counter true issubclass counter_client counter true despite you would be realized soon how useful is this interesting relationship between both types for unit testing let s deal with this later anyway it works nicely as if it s called in a single process under the hood however there s a lot going on such as making an http request how does it work then we can simulate the way counter_client and httptransport objects communicate with the server using curl curl ix post http 0 0 0 0 9322 method increment http 1 0 200 ok content type application json content length 1 vary origin access control allow methods post options 4 it s quite dumb and old fashioned nevertheless it is so simple that in any languages we can call this with only writing few code indeed the protocol is simple and adopts widely used standards like http and json regardless of inefficiency one of nirum s goals is to make any language can easily interoperate with other systems that use nirum even if it is not an official target language of nirum network or runtime efficiency is a non goal or not a top priority at least of the nirum protocol to work well with many platforms nirum provides a way to route fancy url paths to corresponding service methods on the surface these urls can look like http resources of typical http rest apis this feature is enabled through an http resource annotation service counter http resource method post path count bigint increment what do annotations do they per se have no meaning but can be discovered by target backends in compile time or by runtime libraries in run time and may be processed for http resource annotations nirum wsgi server scans them and route an http request to a corresponding method since we have updated counter schema counter nrm it s necessary to recompile them t is a shorthand of target and o is of output dir nirum t python o counter schema out counter schema the above command replaces the existing files in counter schema out directory with python files generated anew and it makes nirum server command to reload the service now the service has a slightly better url path curl ix post http 0 0 0 0 9322 count http 1 0 200 ok content type application json content length 1 vary origin access control allow methods post options 1 you may think the number 1 in the response strange it s because nirum server command reloads the service as the current implementation of countimpl does not save the state into a persistent store e g filesystem database but in memory reloading it makes the state starts from 0 again we can fix this by making state to be saved in a file from counter import counter class counterimpl counter def __init__ self state_path str none self state_path state_path def increment self int try with open self state_path r as f state int f read or 0 state 1 f seek 0 f write str state except filenotfounderror with open self state_path w as f f write 1 state 1 return state although it doesn t work properly for concurrent calls please ignore that now as a result the nirum server process will be unexpectedly terminated with a python traceback detected change in counter server counter_server py reloading restarting with stat traceback most recent call last file counter server venv bin nirum server line 11 in file line 1 in typeerror __init__ missing 1 required positional argument state_path it s because we add a state_path parameter to the constructor of counterimpl class a python expression in the argument of nirum server command also need to be changed notice tmp state in the argument nirum server d counter_server counterimpl tmp state running on http 0 0 0 0 9322 press ctrl c to quit restarting with stat debugger is active debugger pin 123 456 789 we haven t touched the interface but only the implementation so the way to call the service method has not changed curl x post http 0 0 0 0 9322 count 1 curl x post http 0 0 0 0 9322 count 2 now you can observe the persistent state from tmp state file cat tmp state 2 4 if you are familiar with python and python web development you could guess what nirum wsgi package does as the name implies it s a wsgi adapter application taking a nirum service method parameters the previous example was designed to minimize the complexity by intention that s why increment method has no parameters in this chapter the counter example slighly evolves previously increment method only can increment the state by 1 how about making it possible to increment the state by any delta if the previous one is like a microservice version of state this one is like a microservice version of state delta how would the interface be changed service counter http resource method post path count delta bigint increment bigint delta now the increment method has a parameter named delta it s typed as bigint which is the same to the return type the path option of the http resource annotation also changed a variable path component delta is appended it means a post count 123 request corresponds to a increment 123 call as the interface changed we need to recompile it nirum t python o counter schema out counter schema the implementation of increment method also has to be changed def increment self delta int int try with open self state_path r as f state int f read or 0 except filenotfounderror state 0 state delta with open self state_path w as f f write str state return state again as we touched counter_server py the nirum server also reloads the service would it work well then from counter import counter_client from nirum_http import httptransport transport httptransport http 0 0 0 0 9322 client counter_client transport client increment 1 3 client increment 123 126 that s what we ve expected how is it like under the hood curl x post http 0 0 0 0 9322 count 123 249 that also work well server side unit tests although unit testing a microservice is less painful than unit testing a user facing app it is much more complicated than unit testing a library if microservice and library are somewhat analogous in the respect that both are a programming interface why do not write unit tests for a microservice instead of functional tests if unit tests of a traditional library don t deal with calling conventions like cdecl or stdcall why wouldn t unit tests of a microservice ignore network transportation like http data coding or serialization like json because whereas such low level details in traditional libraries are hidden by languages usually still no language is adopted for microservices to hide networking or serialization fortunately we ve defined the interface for our microservice in nirum an idl which hides such low level details the following tests py source shows how is unit testing a microservice like where its interface is defined in nirum import os from tempfile import mkstemp from unittest import testcase from counter_server import counterimpl class counterimpltest testcase def setup self fd self path mkstemp os close fd only path is necessary self counter counterimpl self path def teardown self os unlink self path def test_initial_state self self assertequal 0 self counter increment delta 0 def test_increment self self assertequal 1 self counter increment delta 1 self assertequal 2 self counter increment delta 1 def test_increment_by_5 self self assertequal 5 self counter increment delta 5 self assertequal 10 self counter increment delta 5 the above code uses a unit testing framework named unittest in the python standard library because it is built in so that we don t need to install it and has the most friendly interface which derives from xunit its setup method tries to make a fixture instance of counterimpl since the constructor of counterimpl takes a file path to store its state setup also creates a temporary file and then teardown method removes it after tests finish the rest test_initial_state test_increment and test_increment_by_5 methods test if the counterimpl instance satisfies behaviors we expect it s quite straightforward and concise it doesn t have to test like what if the increment method takes a string instead of an integer or w...
|
