From 96df10361fdbb8b9a8880d98cda125324f8dd611 Mon Sep 17 00:00:00 2001
From: Duchateau Fabien <fabien.duchateau@univ-lyon1.fr>
Date: Tue, 23 Mar 2021 12:58:22 +0100
Subject: [PATCH] [MD] update documentation
---
doc/api.html | 3584 +++++++++++++++++++++++--------------------
doc/index.html | 56 -
doc/integrator.html | 390 -----
setup.py | 2 +-
4 files changed, 1960 insertions(+), 2072 deletions(-)
delete mode 100644 doc/index.html
delete mode 100644 doc/integrator.html
diff --git a/doc/api.html b/doc/api.html
index 864ca64..81147d9 100644
--- a/doc/api.html
+++ b/doc/api.html
@@ -1,1646 +1,1980 @@
<!doctype html>
<html lang="en">
<head>
-<meta charset="utf-8">
-<meta name="viewport" content="width=device-width, initial-scale=1, minimum-scale=1" />
-<meta name="generator" content="pdoc 0.6.3" />
-<title>api API documentation</title>
-<meta name="description" content="" />
-<link href='https://cdnjs.cloudflare.com/ajax/libs/normalize/8.0.0/normalize.min.css' rel='stylesheet'>
-<link href='https://cdnjs.cloudflare.com/ajax/libs/10up-sanitize.css/8.0.0/sanitize.min.css' rel='stylesheet'>
-<link href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/9.12.0/styles/github.min.css" rel="stylesheet">
-<style>.flex{display:flex !important}body{line-height:1.5em}#content{padding:20px}#sidebar{padding:30px;overflow:hidden}.http-server-breadcrumbs{font-size:130%;margin:0 0 15px 0}#footer{font-size:.75em;padding:5px 30px;border-top:1px solid #ddd;text-align:right}#footer p{margin:0 0 0 1em;display:inline-block}#footer p:last-child{margin-right:30px}h1,h2,h3,h4,h5{font-weight:300}h1{font-size:2.5em;line-height:1.1em}h2{font-size:1.75em;margin:1em 0 .50em 0}h3{font-size:1.4em;margin:25px 0 10px 0}h4{margin:0;font-size:105%}a{color:#058;text-decoration:none;transition:color .3s ease-in-out}a:hover{color:#e82}.title code{font-weight:bold}h2[id^="header-"]{margin-top:2em}.ident{color:#900}pre code{background:#f8f8f8;font-size:.8em;line-height:1.4em}code{background:#f2f2f1;padding:1px 4px;overflow-wrap:break-word}h1 code{background:transparent}pre{background:#f8f8f8;border:0;border-top:1px solid #ccc;border-bottom:1px solid #ccc;margin:1em 0;padding:1ex}#http-server-module-list{display:flex;flex-flow:column}#http-server-module-list div{display:flex}#http-server-module-list dt{min-width:10%}#http-server-module-list p{margin-top:0}.toc ul,#index{list-style-type:none;margin:0;padding:0}#index code{background:transparent}#index h3{border-bottom:1px solid #ddd}#index ul{padding:0}#index h4{font-weight:bold}#index h4 + ul{margin-bottom:.6em}@media (min-width:200ex){#index .two-column{column-count:2}}@media (min-width:300ex){#index .two-column{column-count:3}}dl{margin-bottom:2em}dl dl:last-child{margin-bottom:4em}dd{margin:0 0 1em 3em}#header-classes + dl > dd{margin-bottom:3em}dd dd{margin-left:2em}dd p{margin:10px 0}.name{background:#eee;font-weight:bold;font-size:.85em;padding:5px 10px;display:inline-block;min-width:40%}.name:hover{background:#e0e0e0}.name > span:first-child{white-space:nowrap}.name.class > span:nth-child(2){margin-left:.4em}.inherited{color:#999;border-left:5px solid #eee;padding-left:1em}.inheritance em{font-style:normal;font-weight:bold}.desc h2{font-weight:400;font-size:1.25em}.desc h3{font-size:1em}.desc dt code{background:inherit}.source summary{color:#666;text-align:right;font-weight:400;font-size:.8em;text-transform:uppercase;cursor:pointer}.source pre{max-height:500px;overflow:auto;margin:0}.source pre code{font-size:12px;overflow:visible}.hlist{list-style:none}.hlist li{display:inline}.hlist li:after{content:',\2002'}.hlist li:last-child:after{content:none}.hlist .hlist{display:inline;padding-left:1em}img{max-width:100%}.admonition{padding:.1em .5em;margin-bottom:1em}.admonition-title{font-weight:bold}.admonition.note,.admonition.info,.admonition.important{background:#aef}.admonition.todo,.admonition.versionadded,.admonition.tip,.admonition.hint{background:#dfd}.admonition.warning,.admonition.versionchanged,.admonition.deprecated{background:#fd4}.admonition.error,.admonition.danger,.admonition.caution{background:lightpink}</style>
-<style media="screen and (min-width: 700px)">@media screen and (min-width:700px){#sidebar{width:30%}#content{width:70%;max-width:100ch;padding:3em 4em;border-left:1px solid #ddd}pre code{font-size:1em}.item .name{font-size:1em}main{display:flex;flex-direction:row-reverse;justify-content:flex-end}.toc ul ul,#index ul{padding-left:1.5em}.toc > ul > li{margin-top:.5em}}</style>
-<style media="print">@media print{#sidebar h1{page-break-before:always}.source{display:none}}@media print{*{background:transparent !important;color:#000 !important;box-shadow:none !important;text-shadow:none !important}a[href]:after{content:" (" attr(href) ")";font-size:90%}a[href][title]:after{content:none}abbr[title]:after{content:" (" attr(title) ")"}.ir a:after,a[href^="javascript:"]:after,a[href^="#"]:after{content:""}pre,blockquote{border:1px solid #999;page-break-inside:avoid}thead{display:table-header-group}tr,img{page-break-inside:avoid}img{max-width:100% !important}@page{margin:0.5cm}p,h2,h3{orphans:3;widows:3}h1,h2,h3,h4,h5,h6{page-break-after:avoid}}</style>
+ <meta charset="utf-8">
+ <meta name="viewport" content="width=device-width, initial-scale=1">
+ <meta name="generator" content="pdoc 6.4.1" />
+ <title>mongiris.api API documentation</title>
+ <link rel="icon" type="image/svg+xml" href="data:image/svg+xml,%3Csvg%20xmlns%3D%22http%3A//www.w3.org/2000/svg%22%20width%3D%2264%22%20height%3D%2264%22%20viewBox%3D%2244.5%202.5%2015%2015%22%3E%3Cpath%20d%3D%22M49.351%2021.041c-.233-.721-.546-2.408-.772-4.076-.042-.09-.067-.187-.046-.288-.166-1.347-.277-2.625-.241-3.351-1.378-1.008-2.271-2.586-2.271-4.362%200-.976.272-1.935.788-2.774.057-.094.122-.18.184-.268-.033-.167-.052-.339-.052-.516%200-1.477%201.202-2.679%202.679-2.679.791%200%201.496.352%201.987.9a6.3%206.3%200%200%201%201.001.029c.492-.564%201.207-.929%202.012-.929%201.477%200%202.679%201.202%202.679%202.679a2.65%202.65%200%200%201-.269%201.148c.383.747.595%201.572.595%202.41%200%202.311-1.507%204.29-3.635%205.107.037.699.147%202.27.423%203.294l.137.461c.156%202.136-4.612%205.166-5.199%203.215zm.127-4.919a4.78%204.78%200%200%200%20.775-.584c-.172-.115-.505-.254-.88-.378zm.331%202.302l.828-.502c-.202-.143-.576-.328-.984-.49zm.45%202.157l.701-.403c-.214-.115-.536-.249-.891-.376l.19.779zM49.13%204.141c0%20.152.123.276.276.276s.275-.124.275-.276-.123-.276-.276-.276-.275.124-.275.276zm.735-.389a1.15%201.15%200%200%201%20.314.783%201.16%201.16%200%200%201-1.162%201.162c-.457%200-.842-.27-1.032-.653-.026.117-.042.238-.042.362a1.68%201.68%200%200%200%201.679%201.679%201.68%201.68%200%200%200%201.679-1.679c0-.843-.626-1.535-1.436-1.654zm3.076%201.654a1.68%201.68%200%200%200%201.679%201.679%201.68%201.68%200%200%200%201.679-1.679c0-.037-.009-.072-.011-.109-.21.3-.541.508-.935.508a1.16%201.16%200%200%201-1.162-1.162%201.14%201.14%200%200%201%20.474-.912c-.015%200-.03-.005-.045-.005-.926.001-1.679.754-1.679%201.68zm1.861-1.265c0%20.152.123.276.276.276s.275-.124.275-.276-.123-.276-.276-.276-.275.124-.275.276zm1.823%204.823c0-.52-.103-1.035-.288-1.52-.466.394-1.06.64-1.717.64-1.144%200-2.116-.725-2.499-1.738-.383%201.012-1.355%201.738-2.499%201.738-.867%200-1.631-.421-2.121-1.062-.307.605-.478%201.267-.478%201.942%200%202.486%202.153%204.51%204.801%204.51s4.801-2.023%204.801-4.51zm-3.032%209.156l-.146-.492c-.276-1.02-.395-2.457-.444-3.268a6.11%206.11%200%200%201-1.18.115%206.01%206.01%200%200%201-2.536-.562l.006.175c.802.215%201.848.612%202.021%201.25.079.295-.021.601-.274.837l-.598.501c.667.304%201.243.698%201.311%201.179.02.144.022.507-.393.787l-.564.365c1.285.521%201.361.96%201.381%201.126.018.142.011.496-.427.746l-.854.489c.064-1.19%201.985-2.585%202.697-3.248zM49.34%209.925c0-.667%201-.667%201%200%200%20.653.818%201.205%201.787%201.205s1.787-.552%201.787-1.205c0-.667%201-.667%201%200%200%201.216-1.25%202.205-2.787%202.205s-2.787-.989-2.787-2.205zm-.887-7.633c-.093.077-.205.114-.317.114a.5.5%200%200%201-.318-.886L49.183.397a.5.5%200%200%201%20.703.068.5.5%200%200%201-.069.703zm7.661-.065c-.086%200-.173-.022-.253-.068l-1.523-.893c-.575-.337-.069-1.2.506-.863l1.523.892a.5.5%200%200%201%20.179.685c-.094.158-.261.247-.432.247z%22%20fill%3D%22%233bb300%22/%3E%3C/svg%3E"/>
+
+
+<style type="text/css">/*! * Bootstrap Reboot v5.0.0-beta1 (https://getbootstrap.com/) * Copyright 2011-2020 The Bootstrap Authors * Copyright 2011-2020 Twitter, Inc. * Licensed under MIT (https://github.com/twbs/bootstrap/blob/main/LICENSE) * Forked from Normalize.css, licensed MIT (https://github.com/necolas/normalize.css/blob/master/LICENSE.md) */*,::after,::before{box-sizing:border-box}@media (prefers-reduced-motion:no-preference){:root{scroll-behavior:smooth}}body{margin:0;font-family:system-ui,-apple-system,"Segoe UI",Roboto,"Helvetica Neue",Arial,"Noto Sans","Liberation Sans",sans-serif,"Apple Color Emoji","Segoe UI Emoji","Segoe UI Symbol","Noto Color Emoji";font-size:1rem;font-weight:400;line-height:1.5;color:#212529;background-color:#fff;-webkit-text-size-adjust:100%;-webkit-tap-highlight-color:transparent}[tabindex="-1"]:focus:not(:focus-visible){outline:0!important}hr{margin:1rem 0;color:inherit;background-color:currentColor;border:0;opacity:.25}hr:not([size]){height:1px}h1,h2,h3,h4,h5,h6{margin-top:0;margin-bottom:.5rem;font-weight:500;line-height:1.2}h1{font-size:calc(1.375rem + 1.5vw)}@media (min-width:1200px){h1{font-size:2.5rem}}h2{font-size:calc(1.325rem + .9vw)}@media (min-width:1200px){h2{font-size:2rem}}h3{font-size:calc(1.3rem + .6vw)}@media (min-width:1200px){h3{font-size:1.75rem}}h4{font-size:calc(1.275rem + .3vw)}@media (min-width:1200px){h4{font-size:1.5rem}}h5{font-size:1.25rem}h6{font-size:1rem}p{margin-top:0;margin-bottom:1rem}abbr[data-bs-original-title],abbr[title]{text-decoration:underline;-webkit-text-decoration:underline dotted;text-decoration:underline dotted;cursor:help;-webkit-text-decoration-skip-ink:none;text-decoration-skip-ink:none}address{margin-bottom:1rem;font-style:normal;line-height:inherit}ol,ul{padding-left:2rem}dl,ol,ul{margin-top:0;margin-bottom:1rem}ol ol,ol ul,ul ol,ul ul{margin-bottom:0}dt{font-weight:700}dd{margin-bottom:.5rem;margin-left:0}blockquote{margin:0 0 1rem}b,strong{font-weight:bolder}small{font-size:.875em}mark{padding:.2em;background-color:#fcf8e3}sub,sup{position:relative;font-size:.75em;line-height:0;vertical-align:baseline}sub{bottom:-.25em}sup{top:-.5em}a{color:#0d6efd;text-decoration:underline}a:hover{color:#0a58ca}a:not([href]):not([class]),a:not([href]):not([class]):hover{color:inherit;text-decoration:none}code,kbd,pre,samp{font-family:SFMono-Regular,Menlo,Monaco,Consolas,"Liberation Mono","Courier New",monospace;font-size:1em;direction:ltr;unicode-bidi:bidi-override}pre{display:block;margin-top:0;margin-bottom:1rem;overflow:auto;font-size:.875em}pre code{font-size:inherit;color:inherit;word-break:normal}code{font-size:.875em;color:#d63384;word-wrap:break-word}a>code{color:inherit}kbd{padding:.2rem .4rem;font-size:.875em;color:#fff;background-color:#212529;border-radius:.2rem}kbd kbd{padding:0;font-size:1em;font-weight:700}figure{margin:0 0 1rem}img,svg{vertical-align:middle}table{caption-side:bottom;border-collapse:collapse}caption{padding-top:.5rem;padding-bottom:.5rem;color:#6c757d;text-align:left}th{text-align:inherit;text-align:-webkit-match-parent}tbody,td,tfoot,th,thead,tr{border-color:inherit;border-style:solid;border-width:0}label{display:inline-block}button{border-radius:0}button:focus{outline:dotted 1px;outline:-webkit-focus-ring-color auto 5px}button,input,optgroup,select,textarea{margin:0;font-family:inherit;font-size:inherit;line-height:inherit}button,select{text-transform:none}[role=button]{cursor:pointer}select{word-wrap:normal}[list]::-webkit-calendar-picker-indicator{display:none}[type=button],[type=reset],[type=submit],button{-webkit-appearance:button}[type=button]:not(:disabled),[type=reset]:not(:disabled),[type=submit]:not(:disabled),button:not(:disabled){cursor:pointer}::-moz-focus-inner{padding:0;border-style:none}textarea{resize:vertical}fieldset{min-width:0;padding:0;margin:0;border:0}legend{float:left;width:100%;padding:0;margin-bottom:.5rem;font-size:calc(1.275rem + .3vw);line-height:inherit}@media (min-width:1200px){legend{font-size:1.5rem}}legend+*{clear:left}::-webkit-datetime-edit-day-field,::-webkit-datetime-edit-fields-wrapper,::-webkit-datetime-edit-hour-field,::-webkit-datetime-edit-minute,::-webkit-datetime-edit-month-field,::-webkit-datetime-edit-text,::-webkit-datetime-edit-year-field{padding:0}::-webkit-inner-spin-button{height:auto}[type=search]{outline-offset:-2px;-webkit-appearance:textfield}::-webkit-search-decoration{-webkit-appearance:none}::-webkit-color-swatch-wrapper{padding:0}::file-selector-button{font:inherit}::-webkit-file-upload-button{font:inherit;-webkit-appearance:button}output{display:inline-block}iframe{border:0}summary{display:list-item;cursor:pointer}progress{vertical-align:baseline}[hidden]{display:none!important}</style>
+<style type="text/css">/*! pygments syntax highlighting */pre{line-height:125%;}td.linenos pre{color:#000000; background-color:#f0f0f0; padding-left:5px; padding-right:5px;}span.linenos{color:#000000; background-color:#f0f0f0; padding-left:5px; padding-right:5px;}td.linenos pre.special{color:#000000; background-color:#ffffc0; padding-left:5px; padding-right:5px;}span.linenos.special{color:#000000; background-color:#ffffc0; padding-left:5px; padding-right:5px;}.pdoc .hll{background-color:#ffffcc}.pdoc{background:#f8f8f8;}.pdoc .c{color:#408080; font-style:italic}.pdoc .err{border:1px solid #FF0000}.pdoc .k{color:#008000; font-weight:bold}.pdoc .o{color:#666666}.pdoc .ch{color:#408080; font-style:italic}.pdoc .cm{color:#408080; font-style:italic}.pdoc .cp{color:#BC7A00}.pdoc .cpf{color:#408080; font-style:italic}.pdoc .c1{color:#408080; font-style:italic}.pdoc .cs{color:#408080; font-style:italic}.pdoc .gd{color:#A00000}.pdoc .ge{font-style:italic}.pdoc .gr{color:#FF0000}.pdoc .gh{color:#000080; font-weight:bold}.pdoc .gi{color:#00A000}.pdoc .go{color:#888888}.pdoc .gp{color:#000080; font-weight:bold}.pdoc .gs{font-weight:bold}.pdoc .gu{color:#800080; font-weight:bold}.pdoc .gt{color:#0044DD}.pdoc .kc{color:#008000; font-weight:bold}.pdoc .kd{color:#008000; font-weight:bold}.pdoc .kn{color:#008000; font-weight:bold}.pdoc .kp{color:#008000}.pdoc .kr{color:#008000; font-weight:bold}.pdoc .kt{color:#B00040}.pdoc .m{color:#666666}.pdoc .s{color:#BA2121}.pdoc .na{color:#7D9029}.pdoc .nb{color:#008000}.pdoc .nc{color:#0000FF; font-weight:bold}.pdoc .no{color:#880000}.pdoc .nd{color:#AA22FF}.pdoc .ni{color:#999999; font-weight:bold}.pdoc .ne{color:#D2413A; font-weight:bold}.pdoc .nf{color:#0000FF}.pdoc .nl{color:#A0A000}.pdoc .nn{color:#0000FF; font-weight:bold}.pdoc .nt{color:#008000; font-weight:bold}.pdoc .nv{color:#19177C}.pdoc .ow{color:#AA22FF; font-weight:bold}.pdoc .w{color:#bbbbbb}.pdoc .mb{color:#666666}.pdoc .mf{color:#666666}.pdoc .mh{color:#666666}.pdoc .mi{color:#666666}.pdoc .mo{color:#666666}.pdoc .sa{color:#BA2121}.pdoc .sb{color:#BA2121}.pdoc .sc{color:#BA2121}.pdoc .dl{color:#BA2121}.pdoc .sd{color:#BA2121; font-style:italic}.pdoc .s2{color:#BA2121}.pdoc .se{color:#BB6622; font-weight:bold}.pdoc .sh{color:#BA2121}.pdoc .si{color:#BB6688; font-weight:bold}.pdoc .sx{color:#008000}.pdoc .sr{color:#BB6688}.pdoc .s1{color:#BA2121}.pdoc .ss{color:#19177C}.pdoc .bp{color:#008000}.pdoc .fm{color:#0000FF}.pdoc .vc{color:#19177C}.pdoc .vg{color:#19177C}.pdoc .vi{color:#19177C}.pdoc .vm{color:#19177C}.pdoc .il{color:#666666}</style>
+<style type="text/css">/*! pdoc */:root{--pdoc-background:#fff;}.pdoc{--text:#212529;--muted:#6c757d;--link:#3660a5;--link-hover:#1659c5;--code:#f7f7f7;--active:#fff598;--accent:#eee;--accent2:#c1c1c1;--nav-hover:rgba(255, 255, 255, 0.5);--name:#0066BB;--def:#008800;--annotation:#007020;}body{background-color:var(--pdoc-background);}html, body{width:100%;height:100%;}@media (max-width:769px){#navtoggle{cursor:pointer;position:absolute;width:50px;height:40px;top:1rem;right:1rem;border-color:var(--text);color:var(--text);display:flex;opacity:0.8;}#navtoggle:hover{opacity:1;}#togglestate + div{display:none;}#togglestate:checked + div{display:inherit;}main{padding:2rem 3vw;}.git-button{display:none !important;}}@media (min-width:770px){:root{--sidebar-width:clamp(12.5rem, 28vw, 22rem);}nav{position:fixed;overflow:auto;height:100vh;width:var(--sidebar-width);}main{padding:3rem 2rem 3rem calc(var(--sidebar-width) + 3rem);width:calc(54rem + var(--sidebar-width));max-width:100%;}#navtoggle{display:none;}}#togglestate{display:none;}nav.pdoc{--pad:1.75rem;--indent:1.5rem;background-color:var(--accent);border-right:1px solid var(--accent2);box-shadow:0 0 20px rgba(50, 50, 50, .2) inset;padding:0 0 0 var(--pad);overflow-wrap:anywhere;scrollbar-width:thin; scrollbar-color:var(--accent2) transparent }nav.pdoc::-webkit-scrollbar{width:.4rem; }nav.pdoc::-webkit-scrollbar-thumb{background-color:var(--accent2); }nav.pdoc > div{padding:var(--pad) 0;}nav.pdoc .module-list-button{display:inline-flex;align-items:center;color:var(--text);border-color:var(--muted);margin-bottom:1rem;}nav.pdoc .module-list-button:hover{border-color:var(--text);}nav.pdoc ul{list-style:none;padding-left:0;}nav.pdoc li{display:block;margin:0;padding:.2rem 0 .2rem var(--indent);transition:all 100ms;}nav.pdoc > div > ul > li{padding-left:0;}nav.pdoc li:hover{background-color:var(--nav-hover);}nav.pdoc a, nav.pdoc a:hover{color:var(--text);}nav.pdoc a{display:block;}nav.pdoc > h2:first-of-type{margin-top:1.5rem;}nav.pdoc .class:before{content:"class ";color:var(--muted);}nav.pdoc .function:after{content:"()";color:var(--muted);}html, main{scroll-behavior:smooth;}.pdoc{color:var(--text);box-sizing:border-box;line-height:1.5;background:none;}.pdoc .pdoc-button{display:inline-block;border:solid black 1px;border-radius:2px;font-size:.75rem;padding:calc(0.5em - 1px) 1em;transition:100ms all;}.pdoc .visually-hidden{position:absolute !important;width:1px !important;height:1px !important;padding:0 !important;margin:-1px !important;overflow:hidden !important;clip:rect(0, 0, 0, 0) !important;white-space:nowrap !important;border:0 !important;}.pdoc h1, .pdoc h2, .pdoc h3, .pdoc h4{font-weight:300;margin:.3em 0;padding:.2em 0;}.pdoc a{text-decoration:none;color:var(--link);}.pdoc a:hover{color:var(--link-hover);}.pdoc blockquote{margin-left:2rem;}.pdoc pre{background-color:var(--code);border-top:1px solid var(--accent2);border-bottom:1px solid var(--accent2);margin-bottom:1em;padding:.5rem 0 .5rem .5rem;overflow-x:auto;}.pdoc code{color:var(--text);padding:.2em .4em;margin:0;font-size:85%;background-color:var(--code);border-radius:6px;}.pdoc a > code{color:inherit;}.pdoc pre > code{display:inline-block;font-size:inherit;background:none;border:none;padding:0;}.pdoc .modulename{margin-top:0;font-weight:bold;}.pdoc .modulename a{color:var(--link);transition:100ms all;}.pdoc .git-button{float:right;border:solid var(--link) 1px;}.pdoc .git-button:hover{background-color:var(--link);color:var(--pdoc-background);}.pdoc details{--shift:-40px;text-align:right;margin-top:var(--shift);margin-bottom:calc(0px - var(--shift));clear:both;filter:opacity(1);}.pdoc details:not([open]){height:0;overflow:visible;}.pdoc details > summary{font-size:.75rem;cursor:pointer;color:var(--muted);border-width:0;padding:0 .7em;display:inline-block;display:inline list-item;user-select:none;}.pdoc details > summary:focus{outline:0;}.pdoc details > div{margin-top:calc(0px - var(--shift) / 2);text-align:left;}.pdoc .docstring{margin-bottom:1.5rem;}.pdoc > section:first-of-type > .docstring{margin-bottom:3rem;}.pdoc .docstring pre{margin-left:1em;margin-right:1em;}.pdoc h1:target,.pdoc h2:target,.pdoc h3:target,.pdoc h4:target,.pdoc h5:target,.pdoc h6:target{background-color:var(--active);box-shadow:-1rem 0 0 0 var(--active);}.pdoc div:target > .attr,.pdoc section:target > .attr,.pdoc dd:target > a{background-color:var(--active);}.pdoc .attr:hover{filter:contrast(0.95);}.pdoc .headerlink{position:absolute;width:0;margin-left:-1.5rem;line-height:1.4rem;font-size:1.5rem;font-weight:normal;transition:all 100ms ease-in-out;opacity:0;}.pdoc .attr > .headerlink{margin-left:-2.5rem;}.pdoc *:hover > .headerlink,.pdoc *:target > .attr > .headerlink{opacity:1;}.pdoc .attr{color:var(--text);margin:1rem 0 .5rem;padding:.4rem 5rem .4rem 1rem;background-color:var(--accent);}.pdoc .classattr{margin-left:2rem;}.pdoc .name{color:var(--name);font-weight:bold;}.pdoc .def{color:var(--def);font-weight:bold;}.pdoc .signature{white-space:pre-wrap;}.pdoc .annotation{color:var(--annotation);}.pdoc .inherited{margin-left:2rem;}.pdoc .inherited dt{font-weight:700;}.pdoc .inherited dt, .pdoc .inherited dd{display:inline;margin-left:0;margin-bottom:.5rem;}.pdoc .inherited dd:not(:last-child):after{content:", ";}.pdoc .inherited .class:before{content:"class ";}.pdoc .inherited .function a:after{content:"()";}.pdoc .attribution{margin-top:2rem;display:block;opacity:0.5;transition:all 200ms;filter:grayscale(100%);}.pdoc .attribution:hover{opacity:1;filter:grayscale(0%);}.pdoc .attribution img{margin-left:5px;height:35px;vertical-align:middle;width:70px;transition:all 200ms;}</style>
</head>
-<body>
-<main>
-<article id="content">
-<header>
-<h1 class="title">Module <code>api</code></h1>
-</header>
-<section id="section-intro">
-<details class="source">
-<summary>Source code</summary>
-<pre><code class="python">#!/usr/bin/env python
-# encoding: utf-8
-# =============================================================================
-# Abstraction layer for the MongoDB database
-# Performs operations such as find, update, convert_geojson_files, intersect, etc.
-# Some methods are not static because they require a valid DB connection (performed in __init__)
-# =============================================================================
-
-import pymongo
-from bson import json_util # used to convert BSON to JSON (especially ObjectId type of "_id")
-import json
-import logging
-from mongiris import config
-
-
-class Mongiris:
- """
- The Mongiris class is an API to manipulate data from the MongoDB `dbinsee` datatase.
-
- Several methods accepts a 'collection' parameter for flexibility (i.e., be able to query other collections than the
- iris collection).
- Most methods convert resulting documents from the BSON format (MongoDB) to JSON. This mainly avoids the issue of
- ObjectId type (for MongoDB '_id' field).
-
- The constructor initializes the logger and it automatically connects to the database.
- The name of the database and of the three collections
- are based on the default names (the ones from the dump). If the names are changed in MongoDB, they should be changed
- in the `config.py` file.
-
- Examples of usages, including testing geospatial queries, are available in `tests/api_tests.py`.
-
- An example of IRIS following the GeoJSON format is provided in `data/example-iris.json`.
-
- Additional resources:
-
- - [MongoDB documentation](http://www.mongodb.org/)
-
- - [GeoJSON format specifications](https://geojson.org/)
-
- - [pymongo API](http://api.mongodb.com/python/current/) between Python and MongoDB
-
- """
-
- def __init__(self):
- logging.basicConfig(format='[%(levelname)s] - %(name)s - %(asctime)s : %(message)s')
- self.logger = logging.getLogger()
- self.logger.setLevel(logging.INFO)
- self.connection, self.connection_status = self.init_connection() # default connection on 'localhost', 27017
- self.database = self.connection[config.database_iris] # database for HiL project
- self.collection_iris = self.database[config.collection_iris]
- self.collection_indic = self.database[config.collection_indic]
- self.collection_sources = self.database[config.collection_sources]
-
- @staticmethod
- def bson_to_json(doc_bson):
- """
- Converts the bson data to valid JSON (including the ObjectId type converted to {"$oid": <string>}).
-
- Args:
- doc_bson: the BSON data to be converted
-
- Returns:
- doc_json: a JSON object
- """
- doc_json = json.loads(json_util.dumps(doc_bson, json_options=json_util.RELAXED_JSON_OPTIONS))
- return doc_json
-
- def init_connection(self):
- """
- Tries to connect to MongoDB. The output connection object do not provide reliable connection status, only the
- boolean connection_status indicates whether the connection is working or not.
-
- Returns:
- connection: an object with information about the connection
- connection_status: a boolean indicating whether the connection is a success or a failure
- """
- connection_status = True # by default, connection is ok
- connection = None
- try:
- connection = pymongo.MongoClient(serverSelectionTimeoutMS=config.max_timeout) # default localhost:27017
- connection.server_info() # forces a query to MongoDB (for checking the connection)
- except pymongo.errors.ServerSelectionTimeoutError as e:
- self.logger.error('Could not connect to the MongoDB database ! Have you launched MongoDB ? ' + str(e))
- connection_status = False
- return connection, connection_status
-
- @staticmethod
- def _parse_json_to_dict(json_file_path):
- """ Converts a JSON file denoted by json_file_path into a Python dictionary. """
- with open(json_file_path) as data_file:
- data = json.load(data_file)
- data_file.close()
- return data
-
- @staticmethod
- def _save_dict_to_json(json_file_path, dict_geo):
- """ Converts and saves a Python dictionary into a JSON file denoted by json_file_path. """
- with open(json_file_path, 'w') as data_file:
- json.dump(dict_geo, data_file)
-
- def create_index(self, iris_collection):
- """ Rebuilds a geospatial index on the iris collection. Only used in case of restoration/import. """
- self.logger.info("Creating index on 'geometry' using " + pymongo.GEOSPHERE)
- iris_collection.create_index([("geometry", pymongo.GEOSPHERE)])
- self.logger.info("Index created")
-
- def count_documents(self, collection, json_query):
- """
- Counts the number of documents that satisfy json_query in the given collection.
-
- Args:
- collection: a string representing the collection name
- json_query: a dict containing the query criteria (https://docs.mongodb.com/manual/tutorial/query-documents/)
-
- Returns:
- count: an integer representing the number of documents
- """
- return collection.count_documents(json_query)
-
- def find_one_document(self, collection, json_query):
- """
- Finds the first document in the given collection that satisfies json_query.
-
- Args:
- collection: a string representing the collection name
- json_query: a dict containing the query criteria (https://docs.mongodb.com/manual/tutorial/query-documents/)
-
- Returns:
- doc_json: a dictionary representing an iris, or None
- """
- doc = collection.find_one(json_query)
- doc_json = Mongiris.bson_to_json(doc)
- return doc_json
-
- def get_iris_from_code(self, code_iris):
- """
- Returns the iris identified by the given code_iris.
-
- Args:
- code_iris: a string containing the code of the searched iris
-
- Returns:
- iris: a dictionary representing an iris, or None
- """
- iris = self.find_one_document(self.collection_iris, {"properties.CODE_IRIS": code_iris})
- return iris
-
- def find_documents(self, collection, json_query, json_projection=None):
- """
- Finds the first document in the given collection that satisfies json_query.
-
- Args:
- collection: a string representing the collection name
- json_query: a dict containing the query criteria (https://docs.mongodb.com/manual/tutorial/query-documents/)
- json_projection: a json document indicating the fields that appear in the results
-
- Returns:
- doc_json: a cursor (set of documents)
- """
- cursor = collection.find(json_query, json_projection)
- doc_json = Mongiris.bson_to_json(cursor)
- return doc_json
-
- def get_random_document(self, collection):
- """ Returns a random document from the given collection. """
- random_iris = collection.aggregate([{"$sample": {"size": 1}}]).next()
- doc_json = Mongiris.bson_to_json(random_iris)
- return doc_json
-
- def update_one_document(self, collection, json_query, json_updates):
- """
- Updates the first document satisfying json_query by setting new values from json_updates.
-
- Args:
- collection: a string representing the collection name
- json_query: a dict containing the query criteria (https://docs.mongodb.com/manual/tutorial/query-documents/)
- json_updates: a json document containing values to be updates (using $set operator)
-
- Returns:
- json_result: an UpdateResult json document containing information about the operation
- """
- json_result = collection.update_one(json_query, json_updates)
- return json_result
-
- def replace_one_document(self, collection, json_query, json_replace_doc, upsert=False):
- """
- Replaces the first document satisfying json_query by the document json_replace_doc (their _id are identical).
-
- Args:
- collection: a string representing the collection name
- json_query: a dict containing the query criteria (https://docs.mongodb.com/manual/tutorial/query-documents/)
- json_replace_doc: the replacement doc (if _id set, should be the same _id as the doc matching json_query)
- upsert: a boolean, whether the json_replace_doc should be inserted if no document match json_query
-
- Returns:
- json_result: an UpdateResult json document containing information about the operation
- """
- json_result = collection.replace_one(json_query, json_replace_doc, upsert)
- return json_result
-
- def insert_one_document(self, collection, doc):
- """
- Inserts a new document in the collection.
-
- Args:
- collection: a string representing the collection name
- doc: a dict representing the document to be added
-
- Returns:
- json_result: an InsertOneResult json document containing information about the operation
- """
- json_result = collection.insert_one(doc)
- return json_result # eg, the new _id is in json_result.inserted_id
-
- def delete_all(self, collection):
- """
- Deletes all documents in the collection.
-
- Args:
- collection: a string representing the collection name
-
- Returns:
- json_result: an DeleteResult json document containing information about the operation
- """
- json_result = collection.delete_many({}) # empty collection
- return json_result
-
- def geo_within(self, collection, geometry, json_projection=None):
- """
- Finds all documents from given collection and which contain totally the given geometry.
- Cannot be used to find the IRIS containing a point (geometry must be a polygon).
-
- Args:
- collection: a string representing the collection name
- geometry: a geojson geometry ("Polygon", "$box" or "MultiPolygon", NO "Point")
- json_projection: a json document indicating the fields that appear in the results
-
- Returns:
- doc_json: a cursor (set of documents)
- """
- cursor = self.find_documents(collection, {"geometry": {"$geoWithin": {"$geometry": geometry}}}, json_projection)
- doc_json = Mongiris.bson_to_json(cursor)
- return doc_json
-
- def geo_within_sphere(self, collection, sphere, json_projection=None):
- """
- Finds all documents from given collection and which contain totally the given sphere.
- Cannot be used to find the IRIS containing a point (geometry must be a polygon, with min. 3 points).
-
- Args:
- collection: a string representing the collection name
- sphere: a geojson geometry defined by a center and a radius in radians
- json_projection: a json document indicating the fields that appear in the results
-
- Returns:
- doc_json: a cursor (set of documents)
- """
- cursor = self.find_documents(collection, {"geometry": {"$geoWithin": sphere}}, json_projection)
- doc_json = Mongiris.bson_to_json(cursor)
- return doc_json
-
- def intersect(self, collection, geometry, json_projection=None):
- """
- Finds all documents from given collection and which intersect the given geometry.
-
- Args:
- collection: a string representing the collection name
- geometry: a geojson geometry
- json_projection: a json document indicating the fields that appear in the results
-
- Returns:
- doc_json: a cursor (set of documents)
- """
- cursor = self.find_documents(collection, {"geometry": {"$geoIntersects": {
- "$geometry": geometry}}}, json_projection)
- doc_json = Mongiris.bson_to_json(cursor)
- return doc_json
-
- @staticmethod
- def get_geojson_point(coordinates):
- """
- Builds a dictionary with GeoJSON syntax for a point using the given coordinates.
-
- Args:
- coordinates: the coordinates (long, lat) as a list, e.g. [4.8, 45.7]
-
- Returns:
- point: a dictionary with GeoJSON syntax for a Point
- """
- return {"type": "Point", "coordinates": coordinates}
-
- @staticmethod
- def convert_geojson_box_to_polygon(lng1, lat1, lng2, lat2):
- """
- Builds a dictionary with GeoJSON syntax for a polygon using two coordinates (points south-west and north-east).
- This method builds the polygon by adding 2 missing points (north-west and south-east) and adds the starting
- point (south-west) to end the loop.
- The MongoDB $box operator is not supported with 2d-spherical indexes.
-
- Args:
- lng1: longitude of the first point (south-west) of the box
- lat1: latitude of the first point (south-west) of the box
- lng2: longitude of the second point (north-east) of the box
- lat2: latitude of the second point (north-east) of the box
-
- Returns:
- box: a dictionary with GeoJSON syntax for a Box
- """
- coordinates = [[[lng1, lat1], [lng1, lat2], [lng2, lat2], [lng2, lat1], [lng1, lat1]]]
- return Mongiris.get_geojson_polygon(coordinates)
-
- @staticmethod
- def get_geojson_polygon(coordinates):
- """
- Builds a dictionary with GeoJSON syntax for a polygon using the given coordinates.
- Careful: polygons must be closed ! (first coordinate must be identical to last coordinate)
-
- Args:
- coordinates: the coordinates (long, lat) as a list of list, e.g. [[[4.8, 45.7], [4.9, 47.8]]]
-
- Returns:
- polygon: a dictionary with GeoJSON syntax for a Polygon
- """
- return {"type": "Polygon", "coordinates": coordinates}
-
- def point_in_which_iris(self, coordinates, json_projection=None):
- """
- Finds the document (IRIS) containing the given coordinates. Uses near() since geo_within() requires a Polygon.
- Careful: the near() operator may return several iris (low probability since distance = 1 meter) and only the
- first one is returned.
-
- Args:
- coordinates: an array of coordinates (long, lat)
- json_projection: a json document indicating the fields that appear in the results
-
- Returns:
- doc_json: a json document or None
- """
- results = self.near(self.collection_iris, coordinates, json_projection, 1) # distance = 1 meter
- if len(results) == 0:
- return None
- return results[0]
-
- def near(self, collection, coordinates, json_projection=None, distance_max=2000):
- """
- Finds all documents from given collection and which are near the given geometry (according to distance_max).
-
- Args:
- collection: a string representing the collection name
- coordinates: an array of coordinates (long, lat) - near only accepts Point
- json_projection: a json document indicating the fields that appear in the results
- distance_max: the maximum distance of resulting iris, in meters
-
- Returns:
- doc_json: a cursor (set of documents)
- """
- geometry = Mongiris.get_geojson_point(coordinates)
- cursor = self.find_documents(collection, {"geometry": {"$near": {
- "$geometry": geometry, "$maxDistance": distance_max}}}, json_projection)
- doc_json = Mongiris.bson_to_json(cursor)
- return doc_json
-
- @staticmethod
- def adjacent(collection, geometry, json_projection=None, distance=20, exclude_geometry_iris=None):
- """
- Finds all adjacent neighbors of an iris represented by geometry.
- No adjacent function, so use all coordinates of an iris and find the closest iris (according to distance).
- Could be done directly with near(), but near() is less accurate and thus incomplete.
-
- Args:
- collection: a string representing the collection name
- geometry: a geojson geometry (Point, Polygon, etc.)
- json_projection: a json document indicating the fields that appear in the results
- distance: the maximum distance for an adjacent neighbour, in meters (10 to 50 meters are fine)
- exclude_geometry_iris: the document _id of the iris represented by geometry, if it needs to be excluded
-
- Returns:
- doc_json: a cursor (set of documents)
- """
- results = list()
- results_ids = list()
- if exclude_geometry_iris is not None: # to exclude the iris represented by geometry, add it to the results ids
- results_ids.append(exclude_geometry_iris)
- for coords in geometry["coordinates"][0]:
- geometry_coords = Mongiris.get_geojson_point(coords)
- cursor = collection.find({"geometry": {"$near": {"$geometry": geometry_coords,
- "$maxDistance": distance}}}, json_projection)
- for doc in cursor:
- doc_id = doc["_id"]
- if doc_id not in results_ids: # add the new adjacent iris if not already in the results
- results.append(doc)
- results_ids.append(doc_id)
- doc_json = Mongiris.bson_to_json(results)
- return doc_json
-
-
-if __name__ == "__main__":
- print("Run unit tests for testing the Mongiris class.")</code></pre>
-</details>
-</section>
-<section>
-</section>
-<section>
-</section>
-<section>
-</section>
-<section>
-<h2 class="section-title" id="header-classes">Classes</h2>
-<dl>
-<dt id="api.Mongiris"><code class="flex name class">
-<span>class <span class="ident">Mongiris</span></span>
-</code></dt>
-<dd>
-<section class="desc"><p>The Mongiris class is an API to manipulate data from the MongoDB <code>dbinsee</code> datatase.</p>
+<body> <nav class="pdoc">
+ <label id="navtoggle" for="togglestate" class="pdoc-button"><svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 30 30'><path stroke-linecap='round' stroke="currentColor" stroke-miterlimit='10' stroke-width='2' d='M4 7h22M4 15h22M4 23h22'/></svg></label>
+ <input id="togglestate" type="checkbox">
+ <div>
+
+
+
+
+ <h2>API Documentation</h2>
+ <ul class="memberlist">
+ <li>
+ <a class="class" href="#Mongiris">Mongiris</a>
+ <ul class="memberlist">
+ <li>
+ <a class="function" href="#Mongiris.__init__">Mongiris</a>
+ </li>
+ <li>
+ <a class="function" href="#Mongiris.bson_to_json">bson_to_json</a>
+ </li>
+ <li>
+ <a class="function" href="#Mongiris.init_connection">init_connection</a>
+ </li>
+ <li>
+ <a class="function" href="#Mongiris.create_index">create_index</a>
+ </li>
+ <li>
+ <a class="function" href="#Mongiris.count_documents">count_documents</a>
+ </li>
+ <li>
+ <a class="function" href="#Mongiris.find_one_document">find_one_document</a>
+ </li>
+ <li>
+ <a class="function" href="#Mongiris.find_all">find_all</a>
+ </li>
+ <li>
+ <a class="function" href="#Mongiris.get_neighbourhood_from_code">get_neighbourhood_from_code</a>
+ </li>
+ <li>
+ <a class="function" href="#Mongiris.find_documents">find_documents</a>
+ </li>
+ <li>
+ <a class="function" href="#Mongiris.get_random_document">get_random_document</a>
+ </li>
+ <li>
+ <a class="function" href="#Mongiris.update_one_document">update_one_document</a>
+ </li>
+ <li>
+ <a class="function" href="#Mongiris.replace_one_document">replace_one_document</a>
+ </li>
+ <li>
+ <a class="function" href="#Mongiris.insert_one_document">insert_one_document</a>
+ </li>
+ <li>
+ <a class="function" href="#Mongiris.delete_all">delete_all</a>
+ </li>
+ <li>
+ <a class="function" href="#Mongiris.geo_within">geo_within</a>
+ </li>
+ <li>
+ <a class="function" href="#Mongiris.geo_within_sphere">geo_within_sphere</a>
+ </li>
+ <li>
+ <a class="function" href="#Mongiris.intersect">intersect</a>
+ </li>
+ <li>
+ <a class="function" href="#Mongiris.get_geojson_point">get_geojson_point</a>
+ </li>
+ <li>
+ <a class="function" href="#Mongiris.convert_geojson_box_to_polygon">convert_geojson_box_to_polygon</a>
+ </li>
+ <li>
+ <a class="function" href="#Mongiris.get_geojson_polygon">get_geojson_polygon</a>
+ </li>
+ <li>
+ <a class="function" href="#Mongiris.point_in_which_neighbourhood">point_in_which_neighbourhood</a>
+ </li>
+ <li>
+ <a class="function" href="#Mongiris.near">near</a>
+ </li>
+ <li>
+ <a class="function" href="#Mongiris.adjacent">adjacent</a>
+ </li>
+ </ul>
+
+ </li>
+ </ul>
+
+
+ <a class="attribution" title="pdoc: Python API documentation generator" href="https://pdoc.dev">
+ built with <span class="visually-hidden">pdoc</span><img
+ alt="pdoc logo"
+ src="data:image/svg+xml,%3Csvg%20xmlns%3D%22http%3A//www.w3.org/2000/svg%22%20role%3D%22img%22%20aria-label%3D%22pdoc%20logo%22%20width%3D%22300%22%20height%3D%22150%22%20viewBox%3D%22-1%200%2060%2030%22%3E%3Ctitle%3Epdoc%3C/title%3E%3Cpath%20d%3D%22M29.621%2021.293c-.011-.273-.214-.475-.511-.481a.5.5%200%200%200-.489.503l-.044%201.393c-.097.551-.695%201.215-1.566%201.704-.577.428-1.306.486-2.193.182-1.426-.617-2.467-1.654-3.304-2.487l-.173-.172a3.43%203.43%200%200%200-.365-.306.49.49%200%200%200-.286-.196c-1.718-1.06-4.931-1.47-7.353.191l-.219.15c-1.707%201.187-3.413%202.131-4.328%201.03-.02-.027-.49-.685-.141-1.763.233-.721.546-2.408.772-4.076.042-.09.067-.187.046-.288.166-1.347.277-2.625.241-3.351%201.378-1.008%202.271-2.586%202.271-4.362%200-.976-.272-1.935-.788-2.774-.057-.094-.122-.18-.184-.268.033-.167.052-.339.052-.516%200-1.477-1.202-2.679-2.679-2.679-.791%200-1.496.352-1.987.9a6.3%206.3%200%200%200-1.001.029c-.492-.564-1.207-.929-2.012-.929-1.477%200-2.679%201.202-2.679%202.679A2.65%202.65%200%200%200%20.97%206.554c-.383.747-.595%201.572-.595%202.41%200%202.311%201.507%204.29%203.635%205.107-.037.699-.147%202.27-.423%203.294l-.137.461c-.622%202.042-2.515%208.257%201.727%2010.643%201.614.908%203.06%201.248%204.317%201.248%202.665%200%204.492-1.524%205.322-2.401%201.476-1.559%202.886-1.854%206.491.82%201.877%201.393%203.514%201.753%204.861%201.068%202.223-1.713%202.811-3.867%203.399-6.374.077-.846.056-1.469.054-1.537zm-4.835%204.313c-.054.305-.156.586-.242.629-.034-.007-.131-.022-.307-.157-.145-.111-.314-.478-.456-.908.221.121.432.25.675.355.115.039.219.051.33.081zm-2.251-1.238c-.05.33-.158.648-.252.694-.022.001-.125-.018-.307-.157-.217-.166-.488-.906-.639-1.573.358.344.754.693%201.198%201.036zm-3.887-2.337c-.006-.116-.018-.231-.041-.342.635.145%201.189.368%201.599.625.097.231.166.481.174.642-.03.049-.055.101-.067.158-.046.013-.128.026-.298.004-.278-.037-.901-.57-1.367-1.087zm-1.127-.497c.116.306.176.625.12.71-.019.014-.117.045-.345.016-.206-.027-.604-.332-.986-.695.41-.051.816-.056%201.211-.031zm-4.535%201.535c.209.22.379.47.358.598-.006.041-.088.138-.351.234-.144.055-.539-.063-.979-.259a11.66%2011.66%200%200%200%20.972-.573zm.983-.664c.359-.237.738-.418%201.126-.554.25.237.479.548.457.694-.006.042-.087.138-.351.235-.174.064-.694-.105-1.232-.375zm-3.381%201.794c-.022.145-.061.29-.149.401-.133.166-.358.248-.69.251h-.002c-.133%200-.306-.26-.45-.621.417.091.854.07%201.291-.031zm-2.066-8.077a4.78%204.78%200%200%201-.775-.584c.172-.115.505-.254.88-.378l-.105.962zm-.331%202.302a10.32%2010.32%200%200%201-.828-.502c.202-.143.576-.328.984-.49l-.156.992zm-.45%202.157l-.701-.403c.214-.115.536-.249.891-.376a11.57%2011.57%200%200%201-.19.779zm-.181%201.716c.064.398.194.702.298.893-.194-.051-.435-.162-.736-.398.061-.119.224-.3.438-.495zM8.87%204.141c0%20.152-.123.276-.276.276s-.275-.124-.275-.276.123-.276.276-.276.275.124.275.276zm-.735-.389a1.15%201.15%200%200%200-.314.783%201.16%201.16%200%200%200%201.162%201.162c.457%200%20.842-.27%201.032-.653.026.117.042.238.042.362a1.68%201.68%200%200%201-1.679%201.679%201.68%201.68%200%200%201-1.679-1.679c0-.843.626-1.535%201.436-1.654zM5.059%205.406A1.68%201.68%200%200%201%203.38%207.085a1.68%201.68%200%200%201-1.679-1.679c0-.037.009-.072.011-.109.21.3.541.508.935.508a1.16%201.16%200%200%200%201.162-1.162%201.14%201.14%200%200%200-.474-.912c.015%200%20.03-.005.045-.005.926.001%201.679.754%201.679%201.68zM3.198%204.141c0%20.152-.123.276-.276.276s-.275-.124-.275-.276.123-.276.276-.276.275.124.275.276zM1.375%208.964c0-.52.103-1.035.288-1.52.466.394%201.06.64%201.717.64%201.144%200%202.116-.725%202.499-1.738.383%201.012%201.355%201.738%202.499%201.738.867%200%201.631-.421%202.121-1.062.307.605.478%201.267.478%201.942%200%202.486-2.153%204.51-4.801%204.51s-4.801-2.023-4.801-4.51zm24.342%2019.349c-.985.498-2.267.168-3.813-.979-3.073-2.281-5.453-3.199-7.813-.705-1.315%201.391-4.163%203.365-8.423.97-3.174-1.786-2.239-6.266-1.261-9.479l.146-.492c.276-1.02.395-2.457.444-3.268a6.11%206.11%200%200%200%201.18.115%206.01%206.01%200%200%200%202.536-.562l-.006.175c-.802.215-1.848.612-2.021%201.25-.079.295.021.601.274.837.219.203.415.364.598.501-.667.304-1.243.698-1.311%201.179-.02.144-.022.507.393.787.213.144.395.26.564.365-1.285.521-1.361.96-1.381%201.126-.018.142-.011.496.427.746l.854.489c-.473.389-.971.914-.999%201.429-.018.278.095.532.316.713.675.556%201.231.721%201.653.721.059%200%20.104-.014.158-.02.207.707.641%201.64%201.513%201.64h.013c.8-.008%201.236-.345%201.462-.626.173-.216.268-.457.325-.692.424.195.93.374%201.372.374.151%200%20.294-.021.423-.068.732-.27.944-.704.993-1.021.009-.061.003-.119.002-.179.266.086.538.147.789.147.15%200%20.294-.021.423-.069.542-.2.797-.489.914-.754.237.147.478.258.704.288.106.014.205.021.296.021.356%200%20.595-.101.767-.229.438.435%201.094.992%201.656%201.067.106.014.205.021.296.021a1.56%201.56%200%200%200%20.323-.035c.17.575.453%201.289.866%201.605.358.273.665.362.914.362a.99.99%200%200%200%20.421-.093%201.03%201.03%200%200%200%20.245-.164c.168.428.39.846.68%201.068.358.273.665.362.913.362a.99.99%200%200%200%20.421-.093c.317-.148.512-.448.639-.762.251.157.495.257.726.257.127%200%20.25-.024.37-.071.427-.17.706-.617.841-1.314.022-.015.047-.022.068-.038.067-.051.133-.104.196-.159-.443%201.486-1.107%202.761-2.086%203.257zM8.66%209.925a.5.5%200%201%200-1%200c0%20.653-.818%201.205-1.787%201.205s-1.787-.552-1.787-1.205a.5.5%200%201%200-1%200c0%201.216%201.25%202.205%202.787%202.205s2.787-.989%202.787-2.205zm4.4%2015.965l-.208.097c-2.661%201.258-4.708%201.436-6.086.527-1.542-1.017-1.88-3.19-1.844-4.198a.4.4%200%200%200-.385-.414c-.242-.029-.406.164-.414.385-.046%201.249.367%203.686%202.202%204.896.708.467%201.547.7%202.51.7%201.248%200%202.706-.392%204.362-1.174l.185-.086a.4.4%200%200%200%20.205-.527c-.089-.204-.326-.291-.527-.206zM9.547%202.292c.093.077.205.114.317.114a.5.5%200%200%200%20.318-.886L8.817.397a.5.5%200%200%200-.703.068.5.5%200%200%200%20.069.703l1.364%201.124zm-7.661-.065c.086%200%20.173-.022.253-.068l1.523-.893a.5.5%200%200%200-.506-.863l-1.523.892a.5.5%200%200%200-.179.685c.094.158.261.247.432.247z%22%20transform%3D%22matrix%28-1%200%200%201%2058%200%29%22%20fill%3D%22%233bb300%22/%3E%3Cpath%20d%3D%22M.3%2021.86V10.18q0-.46.02-.68.04-.22.18-.5.28-.54%201.34-.54%201.06%200%201.42.28.38.26.44.78.76-1.04%202.38-1.04%201.64%200%203.1%201.54%201.46%201.54%201.46%203.58%200%202.04-1.46%203.58-1.44%201.54-3.08%201.54-1.64%200-2.38-.92v4.04q0%20.46-.04.68-.02.22-.18.5-.14.3-.5.42-.36.12-.98.12-.62%200-1-.12-.36-.12-.52-.4-.14-.28-.18-.5-.02-.22-.02-.68zm3.96-9.42q-.46.54-.46%201.18%200%20.64.46%201.18.48.52%201.2.52.74%200%201.24-.52.52-.52.52-1.18%200-.66-.48-1.18-.48-.54-1.26-.54-.76%200-1.22.54zm14.741-8.36q.16-.3.54-.42.38-.12%201-.12.64%200%201.02.12.38.12.52.42.16.3.18.54.04.22.04.68v11.94q0%20.46-.04.7-.02.22-.18.5-.3.54-1.7.54-1.38%200-1.54-.98-.84.96-2.34.96-1.8%200-3.28-1.56-1.48-1.58-1.48-3.66%200-2.1%201.48-3.68%201.5-1.58%203.28-1.58%201.48%200%202.3%201v-4.2q0-.46.02-.68.04-.24.18-.52zm-3.24%2010.86q.52.54%201.26.54.74%200%201.22-.54.5-.54.5-1.18%200-.66-.48-1.22-.46-.56-1.26-.56-.8%200-1.28.56-.48.54-.48%201.2%200%20.66.52%201.2zm7.833-1.2q0-2.4%201.68-3.96%201.68-1.56%203.84-1.56%202.16%200%203.82%201.56%201.66%201.54%201.66%203.94%200%201.66-.86%202.96-.86%201.28-2.1%201.9-1.22.6-2.54.6-1.32%200-2.56-.64-1.24-.66-2.1-1.92-.84-1.28-.84-2.88zm4.18%201.44q.64.48%201.3.48.66%200%201.32-.5.66-.5.66-1.48%200-.98-.62-1.46-.62-.48-1.34-.48-.72%200-1.34.5-.62.5-.62%201.48%200%20.96.64%201.46zm11.412-1.44q0%20.84.56%201.32.56.46%201.18.46.64%200%201.18-.36.56-.38.9-.38.6%200%201.46%201.06.46.58.46%201.04%200%20.76-1.1%201.42-1.14.8-2.8.8-1.86%200-3.58-1.34-.82-.64-1.34-1.7-.52-1.08-.52-2.36%200-1.3.52-2.34.52-1.06%201.34-1.7%201.66-1.32%203.54-1.32.76%200%201.48.22.72.2%201.06.4l.32.2q.36.24.56.38.52.4.52.92%200%20.5-.42%201.14-.72%201.1-1.38%201.1-.38%200-1.08-.44-.36-.34-1.04-.34-.66%200-1.24.48-.58.48-.58%201.34z%22%20fill%3D%22green%22/%3E%3C/svg%3E"/>
+ </a>
+ </div>
+ </nav>
+ <main class="pdoc">
+ <section>
+ <h1 class="modulename">
+mongiris.api </h1>
+
+
+ <details>
+ <summary>View Source</summary>
+ <div class="codehilite"><pre><span></span><span class="ch">#!/usr/bin/env python</span>
+<span class="c1"># encoding: utf-8</span>
+<span class="c1"># =============================================================================</span>
+<span class="c1"># Abstraction layer for the MongoDB database</span>
+<span class="c1"># Performs operations such as find, update, convert_geojson_files, intersect, etc.</span>
+<span class="c1"># Some methods are not static because they require a valid DB connection (performed in __init__)</span>
+<span class="c1"># =============================================================================</span>
+
+<span class="kn">import</span> <span class="nn">pymongo</span>
+<span class="kn">from</span> <span class="nn">bson</span> <span class="kn">import</span> <span class="n">json_util</span> <span class="c1"># used to convert BSON to JSON (especially ObjectId type of "_id")</span>
+<span class="kn">import</span> <span class="nn">json</span>
+<span class="kn">import</span> <span class="nn">logging</span>
+
+<span class="n">max_timeout</span> <span class="o">=</span> <span class="mi">300000</span> <span class="c1"># delay before connection timeout in milliseconds</span>
+
+<span class="k">class</span> <span class="nc">Mongiris</span><span class="p">:</span>
+ <span class="sd">"""</span>
+<span class="sd"> The Mongiris class is an API to manipulate data from a MongoDB database containing neighbourhoods (GeoJSON format).</span>
+
+<span class="sd"> Several methods accepts a 'collection' parameter for flexibility (i.e., be able to query other collections than the</span>
+<span class="sd"> neighbourhoods collection).</span>
+<span class="sd"> Most methods convert resulting documents from the BSON format (MongoDB) to JSON. This mainly avoids the issue of</span>
+<span class="sd"> ObjectId type (for MongoDB '_id' field).</span>
+
+<span class="sd"> The constructor initializes the logger and it automatically connects to the database.</span>
+<span class="sd"> The name of the database and of the three collections</span>
+<span class="sd"> are based on the default names (the ones from the dump). If the names are changed in MongoDB, they should be changed</span>
+<span class="sd"> in the `config.py` file.</span>
+
+<span class="sd"> Examples of usages, including testing geospatial queries, are available in `tests/api_tests.py`.</span>
+
+<span class="sd"> An example of neighbourhood following the GeoJSON format is provided in `data/example-neighbourhood.json`.</span>
+
+<span class="sd"> Args:</span>
+<span class="sd"> host: the server hosting MongoDB (string, default to 'localhost')</span>
+<span class="sd"> port: the port number on which MongoDB listens to (integer, default tp 27017)</span>
+<span class="sd"> db: the MongoDB database name to connect to (string)</span>
+<span class="sd"> coll_neighbourhoods: the name of the neighbourhoods collection, inside database db (string)</span>
+<span class="sd"> coll_indic: the name of the indicators collection, inside database db (string)</span>
+
+<span class="sd"> Additional resources:</span>
+
+<span class="sd"> - [MongoDB documentation](http://www.mongodb.org/)</span>
+
+<span class="sd"> - [GeoJSON format specifications](https://geojson.org/)</span>
+
+<span class="sd"> - [pymongo API](http://api.mongodb.com/python/current/) between Python and MongoDB</span>
+
+<span class="sd"> """</span>
+
+ <span class="k">def</span> <span class="fm">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">host</span><span class="o">=</span><span class="s1">'localhost'</span><span class="p">,</span> <span class="n">port</span><span class="o">=</span><span class="mi">27017</span><span class="p">,</span> <span class="n">db</span><span class="o">=</span><span class="s1">'dbinsee'</span><span class="p">,</span> <span class="n">coll_neighbourhoods</span><span class="o">=</span><span class="s1">'colliris'</span><span class="p">,</span> <span class="n">coll_indic</span><span class="o">=</span><span class="s1">'collindic'</span><span class="p">):</span>
+ <span class="n">logging</span><span class="o">.</span><span class="n">basicConfig</span><span class="p">(</span><span class="nb">format</span><span class="o">=</span><span class="s1">'[</span><span class="si">%(levelname)s</span><span class="s1">] - </span><span class="si">%(name)s</span><span class="s1"> - </span><span class="si">%(asctime)s</span><span class="s1"> : </span><span class="si">%(message)s</span><span class="s1">'</span><span class="p">)</span>
+ <span class="bp">self</span><span class="o">.</span><span class="n">logger</span> <span class="o">=</span> <span class="n">logging</span><span class="o">.</span><span class="n">getLogger</span><span class="p">()</span>
+ <span class="bp">self</span><span class="o">.</span><span class="n">logger</span><span class="o">.</span><span class="n">setLevel</span><span class="p">(</span><span class="n">logging</span><span class="o">.</span><span class="n">INFO</span><span class="p">)</span>
+ <span class="bp">self</span><span class="o">.</span><span class="n">host</span> <span class="o">=</span> <span class="n">host</span>
+ <span class="bp">self</span><span class="o">.</span><span class="n">port</span> <span class="o">=</span> <span class="n">port</span>
+ <span class="bp">self</span><span class="o">.</span><span class="n">connection</span><span class="p">,</span> <span class="bp">self</span><span class="o">.</span><span class="n">connection_status</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">init_connection</span><span class="p">()</span>
+ <span class="bp">self</span><span class="o">.</span><span class="n">dbname</span> <span class="o">=</span> <span class="n">db</span>
+ <span class="bp">self</span><span class="o">.</span><span class="n">database</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">connection</span><span class="p">[</span><span class="n">db</span><span class="p">]</span> <span class="c1"># link to database</span>
+ <span class="bp">self</span><span class="o">.</span><span class="n">collection_neighbourhoods</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">database</span><span class="p">[</span><span class="n">coll_neighbourhoods</span><span class="p">]</span> <span class="c1"># link to neighbourhoods collection</span>
+ <span class="bp">self</span><span class="o">.</span><span class="n">collection_indicators</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">database</span><span class="p">[</span><span class="n">coll_indic</span><span class="p">]</span> <span class="c1"># link to indicators collection (used for prediction)</span>
+
+ <span class="nd">@staticmethod</span>
+ <span class="k">def</span> <span class="nf">bson_to_json</span><span class="p">(</span><span class="n">doc_bson</span><span class="p">):</span>
+ <span class="sd">"""</span>
+<span class="sd"> Converts the bson data to valid JSON (including the ObjectId type converted to {"$oid": <string>}).</span>
+
+<span class="sd"> Args:</span>
+<span class="sd"> doc_bson: the BSON data to be converted</span>
+
+<span class="sd"> Returns:</span>
+<span class="sd"> doc_json: a JSON object</span>
+<span class="sd"> """</span>
+ <span class="n">doc_json</span> <span class="o">=</span> <span class="n">json</span><span class="o">.</span><span class="n">loads</span><span class="p">(</span><span class="n">json_util</span><span class="o">.</span><span class="n">dumps</span><span class="p">(</span><span class="n">doc_bson</span><span class="p">,</span> <span class="n">json_options</span><span class="o">=</span><span class="n">json_util</span><span class="o">.</span><span class="n">RELAXED_JSON_OPTIONS</span><span class="p">))</span>
+ <span class="k">return</span> <span class="n">doc_json</span>
+
+ <span class="k">def</span> <span class="nf">init_connection</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
+ <span class="sd">"""</span>
+<span class="sd"> Tries to connect to MongoDB (default on localhost:27017). The output connection object do not provide </span>
+<span class="sd"> reliable connection status, only the boolean connection_status indicates whether the connection is </span>
+<span class="sd"> working or not.</span>
+
+<span class="sd"> Returns:</span>
+<span class="sd"> connection: an object with information about the connection</span>
+<span class="sd"> connection_status: a boolean indicating whether the connection is a success or a failure</span>
+<span class="sd"> """</span>
+ <span class="n">connection_status</span> <span class="o">=</span> <span class="kc">True</span> <span class="c1"># by default, connection is ok</span>
+ <span class="n">connection</span> <span class="o">=</span> <span class="kc">None</span>
+ <span class="bp">self</span><span class="o">.</span><span class="n">logger</span><span class="o">.</span><span class="n">info</span><span class="p">(</span><span class="sa">f</span><span class="s1">'Trying to connect to MongoDB server (</span><span class="si">{</span><span class="bp">self</span><span class="o">.</span><span class="n">host</span><span class="si">}</span><span class="s1">:</span><span class="si">{</span><span class="bp">self</span><span class="o">.</span><span class="n">port</span><span class="si">}</span><span class="s1">)...'</span><span class="p">)</span>
+ <span class="k">try</span><span class="p">:</span>
+ <span class="n">connection</span> <span class="o">=</span> <span class="n">pymongo</span><span class="o">.</span><span class="n">MongoClient</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">host</span><span class="p">,</span> <span class="bp">self</span><span class="o">.</span><span class="n">port</span><span class="p">,</span> <span class="n">serverSelectionTimeoutMS</span><span class="o">=</span><span class="n">max_timeout</span><span class="p">)</span>
+ <span class="n">connection</span><span class="o">.</span><span class="n">server_info</span><span class="p">()</span> <span class="c1"># forces a query to MongoDB (for checking the connection)</span>
+ <span class="k">except</span> <span class="n">pymongo</span><span class="o">.</span><span class="n">errors</span><span class="o">.</span><span class="n">ServerSelectionTimeoutError</span> <span class="k">as</span> <span class="n">e</span><span class="p">:</span>
+ <span class="bp">self</span><span class="o">.</span><span class="n">logger</span><span class="o">.</span><span class="n">error</span><span class="p">(</span><span class="s1">'Could not connect to the MongoDB database ! Have you launched MongoDB ? '</span> <span class="o">+</span> <span class="nb">str</span><span class="p">(</span><span class="n">e</span><span class="p">))</span>
+ <span class="n">connection_status</span> <span class="o">=</span> <span class="kc">False</span>
+ <span class="k">return</span> <span class="n">connection</span><span class="p">,</span> <span class="n">connection_status</span>
+
+ <span class="nd">@staticmethod</span>
+ <span class="k">def</span> <span class="nf">_parse_json_to_dict</span><span class="p">(</span><span class="n">json_file_path</span><span class="p">):</span>
+ <span class="sd">""" Converts a JSON file denoted by json_file_path into a Python dictionary. """</span>
+ <span class="k">with</span> <span class="nb">open</span><span class="p">(</span><span class="n">json_file_path</span><span class="p">)</span> <span class="k">as</span> <span class="n">data_file</span><span class="p">:</span>
+ <span class="n">data</span> <span class="o">=</span> <span class="n">json</span><span class="o">.</span><span class="n">load</span><span class="p">(</span><span class="n">data_file</span><span class="p">)</span>
+ <span class="n">data_file</span><span class="o">.</span><span class="n">close</span><span class="p">()</span>
+ <span class="k">return</span> <span class="n">data</span>
+
+ <span class="nd">@staticmethod</span>
+ <span class="k">def</span> <span class="nf">_save_dict_to_json</span><span class="p">(</span><span class="n">json_file_path</span><span class="p">,</span> <span class="n">dict_geo</span><span class="p">):</span>
+ <span class="sd">""" Converts and saves a Python dictionary into a JSON file denoted by json_file_path. """</span>
+ <span class="k">with</span> <span class="nb">open</span><span class="p">(</span><span class="n">json_file_path</span><span class="p">,</span> <span class="s1">'w'</span><span class="p">)</span> <span class="k">as</span> <span class="n">data_file</span><span class="p">:</span>
+ <span class="n">json</span><span class="o">.</span><span class="n">dump</span><span class="p">(</span><span class="n">dict_geo</span><span class="p">,</span> <span class="n">data_file</span><span class="p">)</span>
+
+ <span class="k">def</span> <span class="nf">create_index</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">iris_collection</span><span class="p">):</span>
+ <span class="sd">""" Rebuilds a geospatial index on the iris collection. Only used in case of restoration/import. """</span>
+ <span class="bp">self</span><span class="o">.</span><span class="n">logger</span><span class="o">.</span><span class="n">info</span><span class="p">(</span><span class="s2">"Creating index on 'geometry' using "</span> <span class="o">+</span> <span class="n">pymongo</span><span class="o">.</span><span class="n">GEOSPHERE</span><span class="p">)</span>
+ <span class="n">iris_collection</span><span class="o">.</span><span class="n">create_index</span><span class="p">([(</span><span class="s2">"geometry"</span><span class="p">,</span> <span class="n">pymongo</span><span class="o">.</span><span class="n">GEOSPHERE</span><span class="p">)])</span>
+ <span class="bp">self</span><span class="o">.</span><span class="n">logger</span><span class="o">.</span><span class="n">info</span><span class="p">(</span><span class="s2">"Index created"</span><span class="p">)</span>
+
+ <span class="k">def</span> <span class="nf">count_documents</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">collection</span><span class="p">,</span> <span class="n">json_query</span><span class="p">):</span>
+ <span class="sd">"""</span>
+<span class="sd"> Counts the number of documents that satisfy json_query in the given collection.</span>
+
+<span class="sd"> Args:</span>
+<span class="sd"> collection: a string representing the collection name</span>
+<span class="sd"> json_query: a dict containing the query criteria (https://docs.mongodb.com/manual/tutorial/query-documents/)</span>
+
+<span class="sd"> Returns:</span>
+<span class="sd"> count: an integer representing the number of documents</span>
+<span class="sd"> """</span>
+ <span class="k">return</span> <span class="n">collection</span><span class="o">.</span><span class="n">count_documents</span><span class="p">(</span><span class="n">json_query</span><span class="p">)</span>
+
+ <span class="k">def</span> <span class="nf">find_one_document</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">collection</span><span class="p">,</span> <span class="n">json_query</span><span class="p">):</span>
+ <span class="sd">"""</span>
+<span class="sd"> Finds the first document in the given collection that satisfies json_query.</span>
+
+<span class="sd"> Args:</span>
+<span class="sd"> collection: a string representing the collection name</span>
+<span class="sd"> json_query: a dict containing the query criteria (https://docs.mongodb.com/manual/tutorial/query-documents/)</span>
+
+<span class="sd"> Returns:</span>
+<span class="sd"> doc_json: a dictionary representing an iris, or None</span>
+<span class="sd"> """</span>
+ <span class="n">doc</span> <span class="o">=</span> <span class="n">collection</span><span class="o">.</span><span class="n">find_one</span><span class="p">(</span><span class="n">json_query</span><span class="p">)</span>
+ <span class="n">doc_json</span> <span class="o">=</span> <span class="n">Mongiris</span><span class="o">.</span><span class="n">bson_to_json</span><span class="p">(</span><span class="n">doc</span><span class="p">)</span>
+ <span class="k">return</span> <span class="n">doc_json</span>
+
+ <span class="k">def</span> <span class="nf">find_all</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">collection</span><span class="p">):</span>
+ <span class="sd">"""</span>
+<span class="sd"> Finds all documents in the given collection.</span>
+<span class="sd"> </span>
+<span class="sd"> Args:</span>
+<span class="sd"> collection: a string representing the collection name</span>
+<span class="sd"> </span>
+<span class="sd"> Returns:</span>
+<span class="sd"> doc_json: a dictionnary representing the documents, or None</span>
+<span class="sd"> """</span>
+ <span class="n">doc</span> <span class="o">=</span> <span class="n">collection</span><span class="o">.</span><span class="n">find</span><span class="p">()</span>
+ <span class="n">doc_json</span> <span class="o">=</span> <span class="n">Mongiris</span><span class="o">.</span><span class="n">bson_to_json</span><span class="p">(</span><span class="n">doc</span><span class="p">)</span>
+ <span class="k">return</span> <span class="n">doc_json</span>
+
+ <span class="k">def</span> <span class="nf">find_all</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">collection</span><span class="p">):</span>
+ <span class="sd">"""</span>
+<span class="sd"> Finds all documents in the given collection.</span>
+<span class="sd"> </span>
+<span class="sd"> Args:</span>
+<span class="sd"> collection: a string representing the collection name</span>
+<span class="sd"> </span>
+<span class="sd"> Returns:</span>
+<span class="sd"> doc_json: a dictionnary representing the documents, or None</span>
+<span class="sd"> """</span>
+ <span class="n">doc</span> <span class="o">=</span> <span class="n">collection</span><span class="o">.</span><span class="n">find</span><span class="p">()</span>
+ <span class="n">doc_json</span> <span class="o">=</span> <span class="n">Mongiris</span><span class="o">.</span><span class="n">bson_to_json</span><span class="p">(</span><span class="n">doc</span><span class="p">)</span>
+ <span class="k">return</span> <span class="n">doc_json</span>
+
+ <span class="k">def</span> <span class="nf">get_neighbourhood_from_code</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">code_neighbourhood</span><span class="p">):</span>
+ <span class="sd">"""</span>
+<span class="sd"> Returns the neighbourhood identified by the given code_neighbourhood.</span>
+
+<span class="sd"> Args:</span>
+<span class="sd"> code_neighbourhood: a string containing the code of the searched neighbourhood</span>
+
+<span class="sd"> Returns:</span>
+<span class="sd"> neighbourhood: a dictionary representing a neighbourhood, or None</span>
+<span class="sd"> """</span>
+ <span class="n">neighbourhood</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">find_one_document</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">collection_neighbourhoods</span><span class="p">,</span> <span class="p">{</span><span class="s2">"properties.CODE_IRIS"</span><span class="p">:</span> <span class="n">code_neighbourhood</span><span class="p">})</span>
+ <span class="k">return</span> <span class="n">neighbourhood</span>
+
+ <span class="k">def</span> <span class="nf">find_documents</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">collection</span><span class="p">,</span> <span class="n">json_query</span><span class="p">,</span> <span class="n">json_projection</span><span class="o">=</span><span class="kc">None</span><span class="p">):</span>
+ <span class="sd">"""</span>
+<span class="sd"> Finds the first document in the given collection that satisfies json_query.</span>
+
+<span class="sd"> Args:</span>
+<span class="sd"> collection: a string representing the collection name</span>
+<span class="sd"> json_query: a dict containing the query criteria (https://docs.mongodb.com/manual/tutorial/query-documents/)</span>
+<span class="sd"> json_projection: a json document indicating the fields that appear in the results</span>
+
+<span class="sd"> Returns:</span>
+<span class="sd"> doc_json: a cursor (set of documents)</span>
+<span class="sd"> """</span>
+ <span class="n">cursor</span> <span class="o">=</span> <span class="n">collection</span><span class="o">.</span><span class="n">find</span><span class="p">(</span><span class="n">json_query</span><span class="p">,</span> <span class="n">json_projection</span><span class="p">)</span>
+ <span class="n">doc_json</span> <span class="o">=</span> <span class="n">Mongiris</span><span class="o">.</span><span class="n">bson_to_json</span><span class="p">(</span><span class="n">cursor</span><span class="p">)</span>
+ <span class="k">return</span> <span class="n">doc_json</span>
+
+ <span class="k">def</span> <span class="nf">get_random_document</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">collection</span><span class="p">):</span>
+ <span class="sd">""" Returns a random document from the given collection. """</span>
+ <span class="n">random_iris</span> <span class="o">=</span> <span class="n">collection</span><span class="o">.</span><span class="n">aggregate</span><span class="p">([{</span><span class="s2">"$sample"</span><span class="p">:</span> <span class="p">{</span><span class="s2">"size"</span><span class="p">:</span> <span class="mi">1</span><span class="p">}}])</span><span class="o">.</span><span class="n">next</span><span class="p">()</span>
+ <span class="n">doc_json</span> <span class="o">=</span> <span class="n">Mongiris</span><span class="o">.</span><span class="n">bson_to_json</span><span class="p">(</span><span class="n">random_iris</span><span class="p">)</span>
+ <span class="k">return</span> <span class="n">doc_json</span>
+
+ <span class="k">def</span> <span class="nf">update_one_document</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">collection</span><span class="p">,</span> <span class="n">json_query</span><span class="p">,</span> <span class="n">json_updates</span><span class="p">):</span>
+ <span class="sd">"""</span>
+<span class="sd"> Updates the first document satisfying json_query by setting new values from json_updates.</span>
+
+<span class="sd"> Args:</span>
+<span class="sd"> collection: a string representing the collection name</span>
+<span class="sd"> json_query: a dict containing the query criteria (https://docs.mongodb.com/manual/tutorial/query-documents/)</span>
+<span class="sd"> json_updates: a json document containing values to be updates (using $set operator)</span>
+
+<span class="sd"> Returns:</span>
+<span class="sd"> json_result: an UpdateResult json document containing information about the operation</span>
+<span class="sd"> """</span>
+ <span class="n">json_result</span> <span class="o">=</span> <span class="n">collection</span><span class="o">.</span><span class="n">update_one</span><span class="p">(</span><span class="n">json_query</span><span class="p">,</span> <span class="n">json_updates</span><span class="p">)</span>
+ <span class="k">return</span> <span class="n">json_result</span>
+
+ <span class="k">def</span> <span class="nf">replace_one_document</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">collection</span><span class="p">,</span> <span class="n">json_query</span><span class="p">,</span> <span class="n">json_replace_doc</span><span class="p">,</span> <span class="n">upsert</span><span class="o">=</span><span class="kc">False</span><span class="p">):</span>
+ <span class="sd">"""</span>
+<span class="sd"> Replaces the first document satisfying json_query by the document json_replace_doc (their _id are identical).</span>
+
+<span class="sd"> Args:</span>
+<span class="sd"> collection: a string representing the collection name</span>
+<span class="sd"> json_query: a dict containing the query criteria (https://docs.mongodb.com/manual/tutorial/query-documents/)</span>
+<span class="sd"> json_replace_doc: the replacement doc (if _id set, should be the same _id as the doc matching json_query)</span>
+<span class="sd"> upsert: a boolean, whether the json_replace_doc should be inserted if no document match json_query</span>
+
+<span class="sd"> Returns:</span>
+<span class="sd"> json_result: an UpdateResult json document containing information about the operation</span>
+<span class="sd"> """</span>
+ <span class="n">json_result</span> <span class="o">=</span> <span class="n">collection</span><span class="o">.</span><span class="n">replace_one</span><span class="p">(</span><span class="n">json_query</span><span class="p">,</span> <span class="n">json_replace_doc</span><span class="p">,</span> <span class="n">upsert</span><span class="p">)</span>
+ <span class="k">return</span> <span class="n">json_result</span>
+
+ <span class="k">def</span> <span class="nf">insert_one_document</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">collection</span><span class="p">,</span> <span class="n">doc</span><span class="p">):</span>
+ <span class="sd">"""</span>
+<span class="sd"> Inserts a new document in the collection.</span>
+
+<span class="sd"> Args:</span>
+<span class="sd"> collection: a string representing the collection name</span>
+<span class="sd"> doc: a dict representing the document to be added</span>
+
+<span class="sd"> Returns:</span>
+<span class="sd"> json_result: an InsertOneResult json document containing information about the operation</span>
+<span class="sd"> """</span>
+ <span class="n">json_result</span> <span class="o">=</span> <span class="n">collection</span><span class="o">.</span><span class="n">insert_one</span><span class="p">(</span><span class="n">doc</span><span class="p">)</span>
+ <span class="k">return</span> <span class="n">json_result</span> <span class="c1"># eg, the new _id is in json_result.inserted_id</span>
+
+ <span class="k">def</span> <span class="nf">delete_all</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">collection</span><span class="p">):</span>
+ <span class="sd">"""</span>
+<span class="sd"> Deletes all documents in the collection.</span>
+
+<span class="sd"> Args:</span>
+<span class="sd"> collection: a string representing the collection name</span>
+
+<span class="sd"> Returns:</span>
+<span class="sd"> json_result: an DeleteResult json document containing information about the operation</span>
+<span class="sd"> """</span>
+ <span class="n">json_result</span> <span class="o">=</span> <span class="n">collection</span><span class="o">.</span><span class="n">delete_many</span><span class="p">({})</span> <span class="c1"># empty collection</span>
+ <span class="k">return</span> <span class="n">json_result</span>
+
+ <span class="k">def</span> <span class="nf">geo_within</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">collection</span><span class="p">,</span> <span class="n">geometry</span><span class="p">,</span> <span class="n">json_projection</span><span class="o">=</span><span class="kc">None</span><span class="p">):</span>
+ <span class="sd">"""</span>
+<span class="sd"> Finds all documents from given collection and which contain totally the given geometry.</span>
+<span class="sd"> Cannot be used to find the neighbourhood containing a point (geometry must be a polygon).</span>
+
+<span class="sd"> Args:</span>
+<span class="sd"> collection: a string representing the collection name</span>
+<span class="sd"> geometry: a geojson geometry ("Polygon", "$box" or "MultiPolygon", NO "Point")</span>
+<span class="sd"> json_projection: a json document indicating the fields that appear in the results</span>
+
+<span class="sd"> Returns:</span>
+<span class="sd"> doc_json: a cursor (set of documents)</span>
+<span class="sd"> """</span>
+ <span class="n">cursor</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">find_documents</span><span class="p">(</span><span class="n">collection</span><span class="p">,</span> <span class="p">{</span><span class="s2">"geometry"</span><span class="p">:</span> <span class="p">{</span><span class="s2">"$geoWithin"</span><span class="p">:</span> <span class="p">{</span><span class="s2">"$geometry"</span><span class="p">:</span> <span class="n">geometry</span><span class="p">}}},</span> <span class="n">json_projection</span><span class="p">)</span>
+ <span class="n">doc_json</span> <span class="o">=</span> <span class="n">Mongiris</span><span class="o">.</span><span class="n">bson_to_json</span><span class="p">(</span><span class="n">cursor</span><span class="p">)</span>
+ <span class="k">return</span> <span class="n">doc_json</span>
+
+ <span class="k">def</span> <span class="nf">geo_within_sphere</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">collection</span><span class="p">,</span> <span class="n">sphere</span><span class="p">,</span> <span class="n">json_projection</span><span class="o">=</span><span class="kc">None</span><span class="p">):</span>
+ <span class="sd">"""</span>
+<span class="sd"> Finds all documents from given collection and which contain totally the given sphere.</span>
+<span class="sd"> Cannot be used to find the neighbourhood containing a point (geometry must be a polygon, with min. 3 points).</span>
+
+<span class="sd"> Args:</span>
+<span class="sd"> collection: a string representing the collection name</span>
+<span class="sd"> sphere: a geojson geometry defined by a center and a radius in radians</span>
+<span class="sd"> json_projection: a json document indicating the fields that appear in the results</span>
+
+<span class="sd"> Returns:</span>
+<span class="sd"> doc_json: a cursor (set of documents)</span>
+<span class="sd"> """</span>
+ <span class="n">cursor</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">find_documents</span><span class="p">(</span><span class="n">collection</span><span class="p">,</span> <span class="p">{</span><span class="s2">"geometry"</span><span class="p">:</span> <span class="p">{</span><span class="s2">"$geoWithin"</span><span class="p">:</span> <span class="n">sphere</span><span class="p">}},</span> <span class="n">json_projection</span><span class="p">)</span>
+ <span class="n">doc_json</span> <span class="o">=</span> <span class="n">Mongiris</span><span class="o">.</span><span class="n">bson_to_json</span><span class="p">(</span><span class="n">cursor</span><span class="p">)</span>
+ <span class="k">return</span> <span class="n">doc_json</span>
+
+ <span class="k">def</span> <span class="nf">intersect</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">collection</span><span class="p">,</span> <span class="n">geometry</span><span class="p">,</span> <span class="n">json_projection</span><span class="o">=</span><span class="kc">None</span><span class="p">):</span>
+ <span class="sd">"""</span>
+<span class="sd"> Finds all documents from given collection and which intersect the given geometry.</span>
+
+<span class="sd"> Args:</span>
+<span class="sd"> collection: a string representing the collection name</span>
+<span class="sd"> geometry: a geojson geometry</span>
+<span class="sd"> json_projection: a json document indicating the fields that appear in the results</span>
+
+<span class="sd"> Returns:</span>
+<span class="sd"> doc_json: a cursor (set of documents)</span>
+<span class="sd"> """</span>
+ <span class="n">cursor</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">find_documents</span><span class="p">(</span><span class="n">collection</span><span class="p">,</span> <span class="p">{</span><span class="s2">"geometry"</span><span class="p">:</span> <span class="p">{</span><span class="s2">"$geoIntersects"</span><span class="p">:</span> <span class="p">{</span>
+ <span class="s2">"$geometry"</span><span class="p">:</span> <span class="n">geometry</span><span class="p">}}},</span> <span class="n">json_projection</span><span class="p">)</span>
+ <span class="n">doc_json</span> <span class="o">=</span> <span class="n">Mongiris</span><span class="o">.</span><span class="n">bson_to_json</span><span class="p">(</span><span class="n">cursor</span><span class="p">)</span>
+ <span class="k">return</span> <span class="n">doc_json</span>
+
+ <span class="nd">@staticmethod</span>
+ <span class="k">def</span> <span class="nf">get_geojson_point</span><span class="p">(</span><span class="n">coordinates</span><span class="p">):</span>
+ <span class="sd">"""</span>
+<span class="sd"> Builds a dictionary with GeoJSON syntax for a point using the given coordinates.</span>
+
+<span class="sd"> Args:</span>
+<span class="sd"> coordinates: the coordinates (long, lat) as a list, e.g. [4.8, 45.7]</span>
+
+<span class="sd"> Returns:</span>
+<span class="sd"> point: a dictionary with GeoJSON syntax for a Point</span>
+<span class="sd"> """</span>
+ <span class="k">return</span> <span class="p">{</span><span class="s2">"type"</span><span class="p">:</span> <span class="s2">"Point"</span><span class="p">,</span> <span class="s2">"coordinates"</span><span class="p">:</span> <span class="n">coordinates</span><span class="p">}</span>
+
+ <span class="nd">@staticmethod</span>
+ <span class="k">def</span> <span class="nf">convert_geojson_box_to_polygon</span><span class="p">(</span><span class="n">lng1</span><span class="p">,</span> <span class="n">lat1</span><span class="p">,</span> <span class="n">lng2</span><span class="p">,</span> <span class="n">lat2</span><span class="p">):</span>
+ <span class="sd">"""</span>
+<span class="sd"> Builds a dictionary with GeoJSON syntax for a polygon using two coordinates (points south-west and north-east).</span>
+<span class="sd"> This method builds the polygon by adding 2 missing points (north-west and south-east) and adds the starting</span>
+<span class="sd"> point (south-west) to end the loop.</span>
+<span class="sd"> The MongoDB $box operator is not supported with 2d-spherical indexes.</span>
+
+<span class="sd"> Args:</span>
+<span class="sd"> lng1: longitude of the first point (south-west) of the box</span>
+<span class="sd"> lat1: latitude of the first point (south-west) of the box</span>
+<span class="sd"> lng2: longitude of the second point (north-east) of the box</span>
+<span class="sd"> lat2: latitude of the second point (north-east) of the box</span>
+
+<span class="sd"> Returns:</span>
+<span class="sd"> box: a dictionary with GeoJSON syntax for a Box</span>
+<span class="sd"> """</span>
+ <span class="n">coordinates</span> <span class="o">=</span> <span class="p">[[[</span><span class="n">lng1</span><span class="p">,</span> <span class="n">lat1</span><span class="p">],</span> <span class="p">[</span><span class="n">lng1</span><span class="p">,</span> <span class="n">lat2</span><span class="p">],</span> <span class="p">[</span><span class="n">lng2</span><span class="p">,</span> <span class="n">lat2</span><span class="p">],</span> <span class="p">[</span><span class="n">lng2</span><span class="p">,</span> <span class="n">lat1</span><span class="p">],</span> <span class="p">[</span><span class="n">lng1</span><span class="p">,</span> <span class="n">lat1</span><span class="p">]]]</span>
+ <span class="k">return</span> <span class="n">Mongiris</span><span class="o">.</span><span class="n">get_geojson_polygon</span><span class="p">(</span><span class="n">coordinates</span><span class="p">)</span>
+
+ <span class="nd">@staticmethod</span>
+ <span class="k">def</span> <span class="nf">get_geojson_polygon</span><span class="p">(</span><span class="n">coordinates</span><span class="p">):</span>
+ <span class="sd">"""</span>
+<span class="sd"> Builds a dictionary with GeoJSON syntax for a polygon using the given coordinates.</span>
+<span class="sd"> Careful: polygons must be closed ! (first coordinate must be identical to last coordinate)</span>
+
+<span class="sd"> Args:</span>
+<span class="sd"> coordinates: the coordinates (long, lat) as a list of list, e.g. [[[4.8, 45.7], [4.9, 47.8]]]</span>
+
+<span class="sd"> Returns:</span>
+<span class="sd"> polygon: a dictionary with GeoJSON syntax for a Polygon</span>
+<span class="sd"> """</span>
+ <span class="k">return</span> <span class="p">{</span><span class="s2">"type"</span><span class="p">:</span> <span class="s2">"Polygon"</span><span class="p">,</span> <span class="s2">"coordinates"</span><span class="p">:</span> <span class="n">coordinates</span><span class="p">}</span>
+
+ <span class="k">def</span> <span class="nf">point_in_which_neighbourhood</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">coordinates</span><span class="p">,</span> <span class="n">json_projection</span><span class="o">=</span><span class="kc">None</span><span class="p">):</span>
+ <span class="sd">"""</span>
+<span class="sd"> Finds the document (neighbourhood) containing the given coordinates. Uses near() since geo_within() requires a</span>
+<span class="sd"> Polygon.</span>
+<span class="sd"> Careful: the near() operator may return several neighbourhoods (low probability since distance = 1 meter) and</span>
+<span class="sd"> only the first one is returned.</span>
+
+<span class="sd"> Args:</span>
+<span class="sd"> coordinates: an array of coordinates (long, lat)</span>
+<span class="sd"> json_projection: a json document indicating the fields that appear in the results</span>
+
+<span class="sd"> Returns:</span>
+<span class="sd"> doc_json: a json document or None</span>
+<span class="sd"> """</span>
+ <span class="n">results</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">near</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">collection_neighbourhoods</span><span class="p">,</span> <span class="n">coordinates</span><span class="p">,</span> <span class="n">json_projection</span><span class="p">,</span> <span class="mi">1</span><span class="p">)</span> <span class="c1"># distance = 1 meter</span>
+ <span class="k">if</span> <span class="nb">len</span><span class="p">(</span><span class="n">results</span><span class="p">)</span> <span class="o">==</span> <span class="mi">0</span><span class="p">:</span>
+ <span class="k">return</span> <span class="kc">None</span>
+ <span class="k">return</span> <span class="n">results</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span>
+
+ <span class="k">def</span> <span class="nf">near</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">collection</span><span class="p">,</span> <span class="n">coordinates</span><span class="p">,</span> <span class="n">json_projection</span><span class="o">=</span><span class="kc">None</span><span class="p">,</span> <span class="n">distance_max</span><span class="o">=</span><span class="mi">2000</span><span class="p">):</span>
+ <span class="sd">"""</span>
+<span class="sd"> Finds all documents from given collection and which are near the given geometry (according to distance_max).</span>
+
+<span class="sd"> Args:</span>
+<span class="sd"> collection: a string representing the collection name</span>
+<span class="sd"> coordinates: an array of coordinates (long, lat) - near only accepts Point</span>
+<span class="sd"> json_projection: a json document indicating the fields that appear in the results</span>
+<span class="sd"> distance_max: the maximum distance of resulting iris, in meters</span>
+
+<span class="sd"> Returns:</span>
+<span class="sd"> doc_json: a cursor (set of documents)</span>
+<span class="sd"> """</span>
+ <span class="n">geometry</span> <span class="o">=</span> <span class="n">Mongiris</span><span class="o">.</span><span class="n">get_geojson_point</span><span class="p">(</span><span class="n">coordinates</span><span class="p">)</span>
+ <span class="n">cursor</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">find_documents</span><span class="p">(</span><span class="n">collection</span><span class="p">,</span> <span class="p">{</span><span class="s2">"geometry"</span><span class="p">:</span> <span class="p">{</span><span class="s2">"$near"</span><span class="p">:</span> <span class="p">{</span>
+ <span class="s2">"$geometry"</span><span class="p">:</span> <span class="n">geometry</span><span class="p">,</span> <span class="s2">"$maxDistance"</span><span class="p">:</span> <span class="n">distance_max</span><span class="p">}}},</span> <span class="n">json_projection</span><span class="p">)</span>
+ <span class="n">doc_json</span> <span class="o">=</span> <span class="n">Mongiris</span><span class="o">.</span><span class="n">bson_to_json</span><span class="p">(</span><span class="n">cursor</span><span class="p">)</span>
+ <span class="k">return</span> <span class="n">doc_json</span>
+
+ <span class="nd">@staticmethod</span>
+ <span class="k">def</span> <span class="nf">adjacent</span><span class="p">(</span><span class="n">collection</span><span class="p">,</span> <span class="n">geometry</span><span class="p">,</span> <span class="n">json_projection</span><span class="o">=</span><span class="kc">None</span><span class="p">,</span> <span class="n">distance</span><span class="o">=</span><span class="mi">20</span><span class="p">,</span> <span class="n">exclude_geometry</span><span class="o">=</span><span class="kc">None</span><span class="p">):</span>
+ <span class="sd">"""</span>
+<span class="sd"> Finds all adjacent neighbors of a neighbourhood represented by geometry.</span>
+<span class="sd"> No adjacent function, so use all coordinates of an iris and find the closest neighbourhood (according to</span>
+<span class="sd"> distance). Could be done directly with near(), but near() is less accurate and thus incomplete.</span>
+
+<span class="sd"> Args:</span>
+<span class="sd"> collection: a string representing the collection name</span>
+<span class="sd"> geometry: a geojson geometry (Point, Polygon, etc.)</span>
+<span class="sd"> json_projection: a json document indicating the fields that appear in the results</span>
+<span class="sd"> distance: the maximum distance for an adjacent neighbour, in meters (10 to 50 meters are fine)</span>
+<span class="sd"> exclude_geometry: the document _id of the neighbourhood represented by geometry, if it needs to be excluded</span>
+
+<span class="sd"> Returns:</span>
+<span class="sd"> doc_json: a cursor (set of documents)</span>
+<span class="sd"> """</span>
+ <span class="n">results</span> <span class="o">=</span> <span class="nb">list</span><span class="p">()</span>
+ <span class="n">results_ids</span> <span class="o">=</span> <span class="nb">list</span><span class="p">()</span>
+ <span class="k">if</span> <span class="n">exclude_geometry</span> <span class="ow">is</span> <span class="ow">not</span> <span class="kc">None</span><span class="p">:</span> <span class="c1"># to exclude the neighbourhood represented by geometry, add it to the results ids</span>
+ <span class="n">results_ids</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="n">exclude_geometry</span><span class="p">)</span>
+ <span class="k">for</span> <span class="n">coords</span> <span class="ow">in</span> <span class="n">geometry</span><span class="p">[</span><span class="s2">"coordinates"</span><span class="p">][</span><span class="mi">0</span><span class="p">]:</span>
+ <span class="n">geometry_coords</span> <span class="o">=</span> <span class="n">Mongiris</span><span class="o">.</span><span class="n">get_geojson_point</span><span class="p">(</span><span class="n">coords</span><span class="p">)</span>
+ <span class="n">cursor</span> <span class="o">=</span> <span class="n">collection</span><span class="o">.</span><span class="n">find</span><span class="p">({</span><span class="s2">"geometry"</span><span class="p">:</span> <span class="p">{</span><span class="s2">"$near"</span><span class="p">:</span> <span class="p">{</span><span class="s2">"$geometry"</span><span class="p">:</span> <span class="n">geometry_coords</span><span class="p">,</span>
+ <span class="s2">"$maxDistance"</span><span class="p">:</span> <span class="n">distance</span><span class="p">}}},</span> <span class="n">json_projection</span><span class="p">)</span>
+ <span class="k">for</span> <span class="n">doc</span> <span class="ow">in</span> <span class="n">cursor</span><span class="p">:</span>
+ <span class="n">doc_id</span> <span class="o">=</span> <span class="n">doc</span><span class="p">[</span><span class="s2">"_id"</span><span class="p">]</span>
+ <span class="k">if</span> <span class="n">doc_id</span> <span class="ow">not</span> <span class="ow">in</span> <span class="n">results_ids</span><span class="p">:</span> <span class="c1"># add the new adjacent iris if not already in the results</span>
+ <span class="n">results</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="n">doc</span><span class="p">)</span>
+ <span class="n">results_ids</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="n">doc_id</span><span class="p">)</span>
+ <span class="n">doc_json</span> <span class="o">=</span> <span class="n">Mongiris</span><span class="o">.</span><span class="n">bson_to_json</span><span class="p">(</span><span class="n">results</span><span class="p">)</span>
+ <span class="k">return</span> <span class="n">doc_json</span>
+
+
+<span class="k">if</span> <span class="vm">__name__</span> <span class="o">==</span> <span class="s2">"__main__"</span><span class="p">:</span>
+ <span class="nb">print</span><span class="p">(</span><span class="s2">"Run unit tests for testing the Mongiris class."</span><span class="p">)</span>
+</pre></div>
+
+ </details>
+
+ </section>
+ <section id="Mongiris">
+ <div class="attr class">
+ <a class="headerlink" href="#Mongiris">#  </a>
+
+
+ <span class="def">class</span>
+ <span class="name">Mongiris</span>:
+ </div>
+
+ <details>
+ <summary>View Source</summary>
+ <div class="codehilite"><pre><span></span><span class="k">class</span> <span class="nc">Mongiris</span><span class="p">:</span>
+ <span class="sd">"""</span>
+<span class="sd"> The Mongiris class is an API to manipulate data from a MongoDB database containing neighbourhoods (GeoJSON format).</span>
+
+<span class="sd"> Several methods accepts a 'collection' parameter for flexibility (i.e., be able to query other collections than the</span>
+<span class="sd"> neighbourhoods collection).</span>
+<span class="sd"> Most methods convert resulting documents from the BSON format (MongoDB) to JSON. This mainly avoids the issue of</span>
+<span class="sd"> ObjectId type (for MongoDB '_id' field).</span>
+
+<span class="sd"> The constructor initializes the logger and it automatically connects to the database.</span>
+<span class="sd"> The name of the database and of the three collections</span>
+<span class="sd"> are based on the default names (the ones from the dump). If the names are changed in MongoDB, they should be changed</span>
+<span class="sd"> in the `config.py` file.</span>
+
+<span class="sd"> Examples of usages, including testing geospatial queries, are available in `tests/api_tests.py`.</span>
+
+<span class="sd"> An example of neighbourhood following the GeoJSON format is provided in `data/example-neighbourhood.json`.</span>
+
+<span class="sd"> Args:</span>
+<span class="sd"> host: the server hosting MongoDB (string, default to 'localhost')</span>
+<span class="sd"> port: the port number on which MongoDB listens to (integer, default tp 27017)</span>
+<span class="sd"> db: the MongoDB database name to connect to (string)</span>
+<span class="sd"> coll_neighbourhoods: the name of the neighbourhoods collection, inside database db (string)</span>
+<span class="sd"> coll_indic: the name of the indicators collection, inside database db (string)</span>
+
+<span class="sd"> Additional resources:</span>
+
+<span class="sd"> - [MongoDB documentation](http://www.mongodb.org/)</span>
+
+<span class="sd"> - [GeoJSON format specifications](https://geojson.org/)</span>
+
+<span class="sd"> - [pymongo API](http://api.mongodb.com/python/current/) between Python and MongoDB</span>
+
+<span class="sd"> """</span>
+
+ <span class="k">def</span> <span class="fm">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">host</span><span class="o">=</span><span class="s1">'localhost'</span><span class="p">,</span> <span class="n">port</span><span class="o">=</span><span class="mi">27017</span><span class="p">,</span> <span class="n">db</span><span class="o">=</span><span class="s1">'dbinsee'</span><span class="p">,</span> <span class="n">coll_neighbourhoods</span><span class="o">=</span><span class="s1">'colliris'</span><span class="p">,</span> <span class="n">coll_indic</span><span class="o">=</span><span class="s1">'collindic'</span><span class="p">):</span>
+ <span class="n">logging</span><span class="o">.</span><span class="n">basicConfig</span><span class="p">(</span><span class="nb">format</span><span class="o">=</span><span class="s1">'[</span><span class="si">%(levelname)s</span><span class="s1">] - </span><span class="si">%(name)s</span><span class="s1"> - </span><span class="si">%(asctime)s</span><span class="s1"> : </span><span class="si">%(message)s</span><span class="s1">'</span><span class="p">)</span>
+ <span class="bp">self</span><span class="o">.</span><span class="n">logger</span> <span class="o">=</span> <span class="n">logging</span><span class="o">.</span><span class="n">getLogger</span><span class="p">()</span>
+ <span class="bp">self</span><span class="o">.</span><span class="n">logger</span><span class="o">.</span><span class="n">setLevel</span><span class="p">(</span><span class="n">logging</span><span class="o">.</span><span class="n">INFO</span><span class="p">)</span>
+ <span class="bp">self</span><span class="o">.</span><span class="n">host</span> <span class="o">=</span> <span class="n">host</span>
+ <span class="bp">self</span><span class="o">.</span><span class="n">port</span> <span class="o">=</span> <span class="n">port</span>
+ <span class="bp">self</span><span class="o">.</span><span class="n">connection</span><span class="p">,</span> <span class="bp">self</span><span class="o">.</span><span class="n">connection_status</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">init_connection</span><span class="p">()</span>
+ <span class="bp">self</span><span class="o">.</span><span class="n">dbname</span> <span class="o">=</span> <span class="n">db</span>
+ <span class="bp">self</span><span class="o">.</span><span class="n">database</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">connection</span><span class="p">[</span><span class="n">db</span><span class="p">]</span> <span class="c1"># link to database</span>
+ <span class="bp">self</span><span class="o">.</span><span class="n">collection_neighbourhoods</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">database</span><span class="p">[</span><span class="n">coll_neighbourhoods</span><span class="p">]</span> <span class="c1"># link to neighbourhoods collection</span>
+ <span class="bp">self</span><span class="o">.</span><span class="n">collection_indicators</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">database</span><span class="p">[</span><span class="n">coll_indic</span><span class="p">]</span> <span class="c1"># link to indicators collection (used for prediction)</span>
+
+ <span class="nd">@staticmethod</span>
+ <span class="k">def</span> <span class="nf">bson_to_json</span><span class="p">(</span><span class="n">doc_bson</span><span class="p">):</span>
+ <span class="sd">"""</span>
+<span class="sd"> Converts the bson data to valid JSON (including the ObjectId type converted to {"$oid": <string>}).</span>
+
+<span class="sd"> Args:</span>
+<span class="sd"> doc_bson: the BSON data to be converted</span>
+
+<span class="sd"> Returns:</span>
+<span class="sd"> doc_json: a JSON object</span>
+<span class="sd"> """</span>
+ <span class="n">doc_json</span> <span class="o">=</span> <span class="n">json</span><span class="o">.</span><span class="n">loads</span><span class="p">(</span><span class="n">json_util</span><span class="o">.</span><span class="n">dumps</span><span class="p">(</span><span class="n">doc_bson</span><span class="p">,</span> <span class="n">json_options</span><span class="o">=</span><span class="n">json_util</span><span class="o">.</span><span class="n">RELAXED_JSON_OPTIONS</span><span class="p">))</span>
+ <span class="k">return</span> <span class="n">doc_json</span>
+
+ <span class="k">def</span> <span class="nf">init_connection</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
+ <span class="sd">"""</span>
+<span class="sd"> Tries to connect to MongoDB (default on localhost:27017). The output connection object do not provide </span>
+<span class="sd"> reliable connection status, only the boolean connection_status indicates whether the connection is </span>
+<span class="sd"> working or not.</span>
+
+<span class="sd"> Returns:</span>
+<span class="sd"> connection: an object with information about the connection</span>
+<span class="sd"> connection_status: a boolean indicating whether the connection is a success or a failure</span>
+<span class="sd"> """</span>
+ <span class="n">connection_status</span> <span class="o">=</span> <span class="kc">True</span> <span class="c1"># by default, connection is ok</span>
+ <span class="n">connection</span> <span class="o">=</span> <span class="kc">None</span>
+ <span class="bp">self</span><span class="o">.</span><span class="n">logger</span><span class="o">.</span><span class="n">info</span><span class="p">(</span><span class="sa">f</span><span class="s1">'Trying to connect to MongoDB server (</span><span class="si">{</span><span class="bp">self</span><span class="o">.</span><span class="n">host</span><span class="si">}</span><span class="s1">:</span><span class="si">{</span><span class="bp">self</span><span class="o">.</span><span class="n">port</span><span class="si">}</span><span class="s1">)...'</span><span class="p">)</span>
+ <span class="k">try</span><span class="p">:</span>
+ <span class="n">connection</span> <span class="o">=</span> <span class="n">pymongo</span><span class="o">.</span><span class="n">MongoClient</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">host</span><span class="p">,</span> <span class="bp">self</span><span class="o">.</span><span class="n">port</span><span class="p">,</span> <span class="n">serverSelectionTimeoutMS</span><span class="o">=</span><span class="n">max_timeout</span><span class="p">)</span>
+ <span class="n">connection</span><span class="o">.</span><span class="n">server_info</span><span class="p">()</span> <span class="c1"># forces a query to MongoDB (for checking the connection)</span>
+ <span class="k">except</span> <span class="n">pymongo</span><span class="o">.</span><span class="n">errors</span><span class="o">.</span><span class="n">ServerSelectionTimeoutError</span> <span class="k">as</span> <span class="n">e</span><span class="p">:</span>
+ <span class="bp">self</span><span class="o">.</span><span class="n">logger</span><span class="o">.</span><span class="n">error</span><span class="p">(</span><span class="s1">'Could not connect to the MongoDB database ! Have you launched MongoDB ? '</span> <span class="o">+</span> <span class="nb">str</span><span class="p">(</span><span class="n">e</span><span class="p">))</span>
+ <span class="n">connection_status</span> <span class="o">=</span> <span class="kc">False</span>
+ <span class="k">return</span> <span class="n">connection</span><span class="p">,</span> <span class="n">connection_status</span>
+
+ <span class="nd">@staticmethod</span>
+ <span class="k">def</span> <span class="nf">_parse_json_to_dict</span><span class="p">(</span><span class="n">json_file_path</span><span class="p">):</span>
+ <span class="sd">""" Converts a JSON file denoted by json_file_path into a Python dictionary. """</span>
+ <span class="k">with</span> <span class="nb">open</span><span class="p">(</span><span class="n">json_file_path</span><span class="p">)</span> <span class="k">as</span> <span class="n">data_file</span><span class="p">:</span>
+ <span class="n">data</span> <span class="o">=</span> <span class="n">json</span><span class="o">.</span><span class="n">load</span><span class="p">(</span><span class="n">data_file</span><span class="p">)</span>
+ <span class="n">data_file</span><span class="o">.</span><span class="n">close</span><span class="p">()</span>
+ <span class="k">return</span> <span class="n">data</span>
+
+ <span class="nd">@staticmethod</span>
+ <span class="k">def</span> <span class="nf">_save_dict_to_json</span><span class="p">(</span><span class="n">json_file_path</span><span class="p">,</span> <span class="n">dict_geo</span><span class="p">):</span>
+ <span class="sd">""" Converts and saves a Python dictionary into a JSON file denoted by json_file_path. """</span>
+ <span class="k">with</span> <span class="nb">open</span><span class="p">(</span><span class="n">json_file_path</span><span class="p">,</span> <span class="s1">'w'</span><span class="p">)</span> <span class="k">as</span> <span class="n">data_file</span><span class="p">:</span>
+ <span class="n">json</span><span class="o">.</span><span class="n">dump</span><span class="p">(</span><span class="n">dict_geo</span><span class="p">,</span> <span class="n">data_file</span><span class="p">)</span>
+
+ <span class="k">def</span> <span class="nf">create_index</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">iris_collection</span><span class="p">):</span>
+ <span class="sd">""" Rebuilds a geospatial index on the iris collection. Only used in case of restoration/import. """</span>
+ <span class="bp">self</span><span class="o">.</span><span class="n">logger</span><span class="o">.</span><span class="n">info</span><span class="p">(</span><span class="s2">"Creating index on 'geometry' using "</span> <span class="o">+</span> <span class="n">pymongo</span><span class="o">.</span><span class="n">GEOSPHERE</span><span class="p">)</span>
+ <span class="n">iris_collection</span><span class="o">.</span><span class="n">create_index</span><span class="p">([(</span><span class="s2">"geometry"</span><span class="p">,</span> <span class="n">pymongo</span><span class="o">.</span><span class="n">GEOSPHERE</span><span class="p">)])</span>
+ <span class="bp">self</span><span class="o">.</span><span class="n">logger</span><span class="o">.</span><span class="n">info</span><span class="p">(</span><span class="s2">"Index created"</span><span class="p">)</span>
+
+ <span class="k">def</span> <span class="nf">count_documents</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">collection</span><span class="p">,</span> <span class="n">json_query</span><span class="p">):</span>
+ <span class="sd">"""</span>
+<span class="sd"> Counts the number of documents that satisfy json_query in the given collection.</span>
+
+<span class="sd"> Args:</span>
+<span class="sd"> collection: a string representing the collection name</span>
+<span class="sd"> json_query: a dict containing the query criteria (https://docs.mongodb.com/manual/tutorial/query-documents/)</span>
+
+<span class="sd"> Returns:</span>
+<span class="sd"> count: an integer representing the number of documents</span>
+<span class="sd"> """</span>
+ <span class="k">return</span> <span class="n">collection</span><span class="o">.</span><span class="n">count_documents</span><span class="p">(</span><span class="n">json_query</span><span class="p">)</span>
+
+ <span class="k">def</span> <span class="nf">find_one_document</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">collection</span><span class="p">,</span> <span class="n">json_query</span><span class="p">):</span>
+ <span class="sd">"""</span>
+<span class="sd"> Finds the first document in the given collection that satisfies json_query.</span>
+
+<span class="sd"> Args:</span>
+<span class="sd"> collection: a string representing the collection name</span>
+<span class="sd"> json_query: a dict containing the query criteria (https://docs.mongodb.com/manual/tutorial/query-documents/)</span>
+
+<span class="sd"> Returns:</span>
+<span class="sd"> doc_json: a dictionary representing an iris, or None</span>
+<span class="sd"> """</span>
+ <span class="n">doc</span> <span class="o">=</span> <span class="n">collection</span><span class="o">.</span><span class="n">find_one</span><span class="p">(</span><span class="n">json_query</span><span class="p">)</span>
+ <span class="n">doc_json</span> <span class="o">=</span> <span class="n">Mongiris</span><span class="o">.</span><span class="n">bson_to_json</span><span class="p">(</span><span class="n">doc</span><span class="p">)</span>
+ <span class="k">return</span> <span class="n">doc_json</span>
+
+ <span class="k">def</span> <span class="nf">find_all</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">collection</span><span class="p">):</span>
+ <span class="sd">"""</span>
+<span class="sd"> Finds all documents in the given collection.</span>
+<span class="sd"> </span>
+<span class="sd"> Args:</span>
+<span class="sd"> collection: a string representing the collection name</span>
+<span class="sd"> </span>
+<span class="sd"> Returns:</span>
+<span class="sd"> doc_json: a dictionnary representing the documents, or None</span>
+<span class="sd"> """</span>
+ <span class="n">doc</span> <span class="o">=</span> <span class="n">collection</span><span class="o">.</span><span class="n">find</span><span class="p">()</span>
+ <span class="n">doc_json</span> <span class="o">=</span> <span class="n">Mongiris</span><span class="o">.</span><span class="n">bson_to_json</span><span class="p">(</span><span class="n">doc</span><span class="p">)</span>
+ <span class="k">return</span> <span class="n">doc_json</span>
+
+ <span class="k">def</span> <span class="nf">find_all</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">collection</span><span class="p">):</span>
+ <span class="sd">"""</span>
+<span class="sd"> Finds all documents in the given collection.</span>
+<span class="sd"> </span>
+<span class="sd"> Args:</span>
+<span class="sd"> collection: a string representing the collection name</span>
+<span class="sd"> </span>
+<span class="sd"> Returns:</span>
+<span class="sd"> doc_json: a dictionnary representing the documents, or None</span>
+<span class="sd"> """</span>
+ <span class="n">doc</span> <span class="o">=</span> <span class="n">collection</span><span class="o">.</span><span class="n">find</span><span class="p">()</span>
+ <span class="n">doc_json</span> <span class="o">=</span> <span class="n">Mongiris</span><span class="o">.</span><span class="n">bson_to_json</span><span class="p">(</span><span class="n">doc</span><span class="p">)</span>
+ <span class="k">return</span> <span class="n">doc_json</span>
+
+ <span class="k">def</span> <span class="nf">get_neighbourhood_from_code</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">code_neighbourhood</span><span class="p">):</span>
+ <span class="sd">"""</span>
+<span class="sd"> Returns the neighbourhood identified by the given code_neighbourhood.</span>
+
+<span class="sd"> Args:</span>
+<span class="sd"> code_neighbourhood: a string containing the code of the searched neighbourhood</span>
+
+<span class="sd"> Returns:</span>
+<span class="sd"> neighbourhood: a dictionary representing a neighbourhood, or None</span>
+<span class="sd"> """</span>
+ <span class="n">neighbourhood</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">find_one_document</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">collection_neighbourhoods</span><span class="p">,</span> <span class="p">{</span><span class="s2">"properties.CODE_IRIS"</span><span class="p">:</span> <span class="n">code_neighbourhood</span><span class="p">})</span>
+ <span class="k">return</span> <span class="n">neighbourhood</span>
+
+ <span class="k">def</span> <span class="nf">find_documents</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">collection</span><span class="p">,</span> <span class="n">json_query</span><span class="p">,</span> <span class="n">json_projection</span><span class="o">=</span><span class="kc">None</span><span class="p">):</span>
+ <span class="sd">"""</span>
+<span class="sd"> Finds the first document in the given collection that satisfies json_query.</span>
+
+<span class="sd"> Args:</span>
+<span class="sd"> collection: a string representing the collection name</span>
+<span class="sd"> json_query: a dict containing the query criteria (https://docs.mongodb.com/manual/tutorial/query-documents/)</span>
+<span class="sd"> json_projection: a json document indicating the fields that appear in the results</span>
+
+<span class="sd"> Returns:</span>
+<span class="sd"> doc_json: a cursor (set of documents)</span>
+<span class="sd"> """</span>
+ <span class="n">cursor</span> <span class="o">=</span> <span class="n">collection</span><span class="o">.</span><span class="n">find</span><span class="p">(</span><span class="n">json_query</span><span class="p">,</span> <span class="n">json_projection</span><span class="p">)</span>
+ <span class="n">doc_json</span> <span class="o">=</span> <span class="n">Mongiris</span><span class="o">.</span><span class="n">bson_to_json</span><span class="p">(</span><span class="n">cursor</span><span class="p">)</span>
+ <span class="k">return</span> <span class="n">doc_json</span>
+
+ <span class="k">def</span> <span class="nf">get_random_document</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">collection</span><span class="p">):</span>
+ <span class="sd">""" Returns a random document from the given collection. """</span>
+ <span class="n">random_iris</span> <span class="o">=</span> <span class="n">collection</span><span class="o">.</span><span class="n">aggregate</span><span class="p">([{</span><span class="s2">"$sample"</span><span class="p">:</span> <span class="p">{</span><span class="s2">"size"</span><span class="p">:</span> <span class="mi">1</span><span class="p">}}])</span><span class="o">.</span><span class="n">next</span><span class="p">()</span>
+ <span class="n">doc_json</span> <span class="o">=</span> <span class="n">Mongiris</span><span class="o">.</span><span class="n">bson_to_json</span><span class="p">(</span><span class="n">random_iris</span><span class="p">)</span>
+ <span class="k">return</span> <span class="n">doc_json</span>
+
+ <span class="k">def</span> <span class="nf">update_one_document</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">collection</span><span class="p">,</span> <span class="n">json_query</span><span class="p">,</span> <span class="n">json_updates</span><span class="p">):</span>
+ <span class="sd">"""</span>
+<span class="sd"> Updates the first document satisfying json_query by setting new values from json_updates.</span>
+
+<span class="sd"> Args:</span>
+<span class="sd"> collection: a string representing the collection name</span>
+<span class="sd"> json_query: a dict containing the query criteria (https://docs.mongodb.com/manual/tutorial/query-documents/)</span>
+<span class="sd"> json_updates: a json document containing values to be updates (using $set operator)</span>
+
+<span class="sd"> Returns:</span>
+<span class="sd"> json_result: an UpdateResult json document containing information about the operation</span>
+<span class="sd"> """</span>
+ <span class="n">json_result</span> <span class="o">=</span> <span class="n">collection</span><span class="o">.</span><span class="n">update_one</span><span class="p">(</span><span class="n">json_query</span><span class="p">,</span> <span class="n">json_updates</span><span class="p">)</span>
+ <span class="k">return</span> <span class="n">json_result</span>
+
+ <span class="k">def</span> <span class="nf">replace_one_document</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">collection</span><span class="p">,</span> <span class="n">json_query</span><span class="p">,</span> <span class="n">json_replace_doc</span><span class="p">,</span> <span class="n">upsert</span><span class="o">=</span><span class="kc">False</span><span class="p">):</span>
+ <span class="sd">"""</span>
+<span class="sd"> Replaces the first document satisfying json_query by the document json_replace_doc (their _id are identical).</span>
+
+<span class="sd"> Args:</span>
+<span class="sd"> collection: a string representing the collection name</span>
+<span class="sd"> json_query: a dict containing the query criteria (https://docs.mongodb.com/manual/tutorial/query-documents/)</span>
+<span class="sd"> json_replace_doc: the replacement doc (if _id set, should be the same _id as the doc matching json_query)</span>
+<span class="sd"> upsert: a boolean, whether the json_replace_doc should be inserted if no document match json_query</span>
+
+<span class="sd"> Returns:</span>
+<span class="sd"> json_result: an UpdateResult json document containing information about the operation</span>
+<span class="sd"> """</span>
+ <span class="n">json_result</span> <span class="o">=</span> <span class="n">collection</span><span class="o">.</span><span class="n">replace_one</span><span class="p">(</span><span class="n">json_query</span><span class="p">,</span> <span class="n">json_replace_doc</span><span class="p">,</span> <span class="n">upsert</span><span class="p">)</span>
+ <span class="k">return</span> <span class="n">json_result</span>
+
+ <span class="k">def</span> <span class="nf">insert_one_document</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">collection</span><span class="p">,</span> <span class="n">doc</span><span class="p">):</span>
+ <span class="sd">"""</span>
+<span class="sd"> Inserts a new document in the collection.</span>
+
+<span class="sd"> Args:</span>
+<span class="sd"> collection: a string representing the collection name</span>
+<span class="sd"> doc: a dict representing the document to be added</span>
+
+<span class="sd"> Returns:</span>
+<span class="sd"> json_result: an InsertOneResult json document containing information about the operation</span>
+<span class="sd"> """</span>
+ <span class="n">json_result</span> <span class="o">=</span> <span class="n">collection</span><span class="o">.</span><span class="n">insert_one</span><span class="p">(</span><span class="n">doc</span><span class="p">)</span>
+ <span class="k">return</span> <span class="n">json_result</span> <span class="c1"># eg, the new _id is in json_result.inserted_id</span>
+
+ <span class="k">def</span> <span class="nf">delete_all</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">collection</span><span class="p">):</span>
+ <span class="sd">"""</span>
+<span class="sd"> Deletes all documents in the collection.</span>
+
+<span class="sd"> Args:</span>
+<span class="sd"> collection: a string representing the collection name</span>
+
+<span class="sd"> Returns:</span>
+<span class="sd"> json_result: an DeleteResult json document containing information about the operation</span>
+<span class="sd"> """</span>
+ <span class="n">json_result</span> <span class="o">=</span> <span class="n">collection</span><span class="o">.</span><span class="n">delete_many</span><span class="p">({})</span> <span class="c1"># empty collection</span>
+ <span class="k">return</span> <span class="n">json_result</span>
+
+ <span class="k">def</span> <span class="nf">geo_within</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">collection</span><span class="p">,</span> <span class="n">geometry</span><span class="p">,</span> <span class="n">json_projection</span><span class="o">=</span><span class="kc">None</span><span class="p">):</span>
+ <span class="sd">"""</span>
+<span class="sd"> Finds all documents from given collection and which contain totally the given geometry.</span>
+<span class="sd"> Cannot be used to find the neighbourhood containing a point (geometry must be a polygon).</span>
+
+<span class="sd"> Args:</span>
+<span class="sd"> collection: a string representing the collection name</span>
+<span class="sd"> geometry: a geojson geometry ("Polygon", "$box" or "MultiPolygon", NO "Point")</span>
+<span class="sd"> json_projection: a json document indicating the fields that appear in the results</span>
+
+<span class="sd"> Returns:</span>
+<span class="sd"> doc_json: a cursor (set of documents)</span>
+<span class="sd"> """</span>
+ <span class="n">cursor</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">find_documents</span><span class="p">(</span><span class="n">collection</span><span class="p">,</span> <span class="p">{</span><span class="s2">"geometry"</span><span class="p">:</span> <span class="p">{</span><span class="s2">"$geoWithin"</span><span class="p">:</span> <span class="p">{</span><span class="s2">"$geometry"</span><span class="p">:</span> <span class="n">geometry</span><span class="p">}}},</span> <span class="n">json_projection</span><span class="p">)</span>
+ <span class="n">doc_json</span> <span class="o">=</span> <span class="n">Mongiris</span><span class="o">.</span><span class="n">bson_to_json</span><span class="p">(</span><span class="n">cursor</span><span class="p">)</span>
+ <span class="k">return</span> <span class="n">doc_json</span>
+
+ <span class="k">def</span> <span class="nf">geo_within_sphere</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">collection</span><span class="p">,</span> <span class="n">sphere</span><span class="p">,</span> <span class="n">json_projection</span><span class="o">=</span><span class="kc">None</span><span class="p">):</span>
+ <span class="sd">"""</span>
+<span class="sd"> Finds all documents from given collection and which contain totally the given sphere.</span>
+<span class="sd"> Cannot be used to find the neighbourhood containing a point (geometry must be a polygon, with min. 3 points).</span>
+
+<span class="sd"> Args:</span>
+<span class="sd"> collection: a string representing the collection name</span>
+<span class="sd"> sphere: a geojson geometry defined by a center and a radius in radians</span>
+<span class="sd"> json_projection: a json document indicating the fields that appear in the results</span>
+
+<span class="sd"> Returns:</span>
+<span class="sd"> doc_json: a cursor (set of documents)</span>
+<span class="sd"> """</span>
+ <span class="n">cursor</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">find_documents</span><span class="p">(</span><span class="n">collection</span><span class="p">,</span> <span class="p">{</span><span class="s2">"geometry"</span><span class="p">:</span> <span class="p">{</span><span class="s2">"$geoWithin"</span><span class="p">:</span> <span class="n">sphere</span><span class="p">}},</span> <span class="n">json_projection</span><span class="p">)</span>
+ <span class="n">doc_json</span> <span class="o">=</span> <span class="n">Mongiris</span><span class="o">.</span><span class="n">bson_to_json</span><span class="p">(</span><span class="n">cursor</span><span class="p">)</span>
+ <span class="k">return</span> <span class="n">doc_json</span>
+
+ <span class="k">def</span> <span class="nf">intersect</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">collection</span><span class="p">,</span> <span class="n">geometry</span><span class="p">,</span> <span class="n">json_projection</span><span class="o">=</span><span class="kc">None</span><span class="p">):</span>
+ <span class="sd">"""</span>
+<span class="sd"> Finds all documents from given collection and which intersect the given geometry.</span>
+
+<span class="sd"> Args:</span>
+<span class="sd"> collection: a string representing the collection name</span>
+<span class="sd"> geometry: a geojson geometry</span>
+<span class="sd"> json_projection: a json document indicating the fields that appear in the results</span>
+
+<span class="sd"> Returns:</span>
+<span class="sd"> doc_json: a cursor (set of documents)</span>
+<span class="sd"> """</span>
+ <span class="n">cursor</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">find_documents</span><span class="p">(</span><span class="n">collection</span><span class="p">,</span> <span class="p">{</span><span class="s2">"geometry"</span><span class="p">:</span> <span class="p">{</span><span class="s2">"$geoIntersects"</span><span class="p">:</span> <span class="p">{</span>
+ <span class="s2">"$geometry"</span><span class="p">:</span> <span class="n">geometry</span><span class="p">}}},</span> <span class="n">json_projection</span><span class="p">)</span>
+ <span class="n">doc_json</span> <span class="o">=</span> <span class="n">Mongiris</span><span class="o">.</span><span class="n">bson_to_json</span><span class="p">(</span><span class="n">cursor</span><span class="p">)</span>
+ <span class="k">return</span> <span class="n">doc_json</span>
+
+ <span class="nd">@staticmethod</span>
+ <span class="k">def</span> <span class="nf">get_geojson_point</span><span class="p">(</span><span class="n">coordinates</span><span class="p">):</span>
+ <span class="sd">"""</span>
+<span class="sd"> Builds a dictionary with GeoJSON syntax for a point using the given coordinates.</span>
+
+<span class="sd"> Args:</span>
+<span class="sd"> coordinates: the coordinates (long, lat) as a list, e.g. [4.8, 45.7]</span>
+
+<span class="sd"> Returns:</span>
+<span class="sd"> point: a dictionary with GeoJSON syntax for a Point</span>
+<span class="sd"> """</span>
+ <span class="k">return</span> <span class="p">{</span><span class="s2">"type"</span><span class="p">:</span> <span class="s2">"Point"</span><span class="p">,</span> <span class="s2">"coordinates"</span><span class="p">:</span> <span class="n">coordinates</span><span class="p">}</span>
+
+ <span class="nd">@staticmethod</span>
+ <span class="k">def</span> <span class="nf">convert_geojson_box_to_polygon</span><span class="p">(</span><span class="n">lng1</span><span class="p">,</span> <span class="n">lat1</span><span class="p">,</span> <span class="n">lng2</span><span class="p">,</span> <span class="n">lat2</span><span class="p">):</span>
+ <span class="sd">"""</span>
+<span class="sd"> Builds a dictionary with GeoJSON syntax for a polygon using two coordinates (points south-west and north-east).</span>
+<span class="sd"> This method builds the polygon by adding 2 missing points (north-west and south-east) and adds the starting</span>
+<span class="sd"> point (south-west) to end the loop.</span>
+<span class="sd"> The MongoDB $box operator is not supported with 2d-spherical indexes.</span>
+
+<span class="sd"> Args:</span>
+<span class="sd"> lng1: longitude of the first point (south-west) of the box</span>
+<span class="sd"> lat1: latitude of the first point (south-west) of the box</span>
+<span class="sd"> lng2: longitude of the second point (north-east) of the box</span>
+<span class="sd"> lat2: latitude of the second point (north-east) of the box</span>
+
+<span class="sd"> Returns:</span>
+<span class="sd"> box: a dictionary with GeoJSON syntax for a Box</span>
+<span class="sd"> """</span>
+ <span class="n">coordinates</span> <span class="o">=</span> <span class="p">[[[</span><span class="n">lng1</span><span class="p">,</span> <span class="n">lat1</span><span class="p">],</span> <span class="p">[</span><span class="n">lng1</span><span class="p">,</span> <span class="n">lat2</span><span class="p">],</span> <span class="p">[</span><span class="n">lng2</span><span class="p">,</span> <span class="n">lat2</span><span class="p">],</span> <span class="p">[</span><span class="n">lng2</span><span class="p">,</span> <span class="n">lat1</span><span class="p">],</span> <span class="p">[</span><span class="n">lng1</span><span class="p">,</span> <span class="n">lat1</span><span class="p">]]]</span>
+ <span class="k">return</span> <span class="n">Mongiris</span><span class="o">.</span><span class="n">get_geojson_polygon</span><span class="p">(</span><span class="n">coordinates</span><span class="p">)</span>
+
+ <span class="nd">@staticmethod</span>
+ <span class="k">def</span> <span class="nf">get_geojson_polygon</span><span class="p">(</span><span class="n">coordinates</span><span class="p">):</span>
+ <span class="sd">"""</span>
+<span class="sd"> Builds a dictionary with GeoJSON syntax for a polygon using the given coordinates.</span>
+<span class="sd"> Careful: polygons must be closed ! (first coordinate must be identical to last coordinate)</span>
+
+<span class="sd"> Args:</span>
+<span class="sd"> coordinates: the coordinates (long, lat) as a list of list, e.g. [[[4.8, 45.7], [4.9, 47.8]]]</span>
+
+<span class="sd"> Returns:</span>
+<span class="sd"> polygon: a dictionary with GeoJSON syntax for a Polygon</span>
+<span class="sd"> """</span>
+ <span class="k">return</span> <span class="p">{</span><span class="s2">"type"</span><span class="p">:</span> <span class="s2">"Polygon"</span><span class="p">,</span> <span class="s2">"coordinates"</span><span class="p">:</span> <span class="n">coordinates</span><span class="p">}</span>
+
+ <span class="k">def</span> <span class="nf">point_in_which_neighbourhood</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">coordinates</span><span class="p">,</span> <span class="n">json_projection</span><span class="o">=</span><span class="kc">None</span><span class="p">):</span>
+ <span class="sd">"""</span>
+<span class="sd"> Finds the document (neighbourhood) containing the given coordinates. Uses near() since geo_within() requires a</span>
+<span class="sd"> Polygon.</span>
+<span class="sd"> Careful: the near() operator may return several neighbourhoods (low probability since distance = 1 meter) and</span>
+<span class="sd"> only the first one is returned.</span>
+
+<span class="sd"> Args:</span>
+<span class="sd"> coordinates: an array of coordinates (long, lat)</span>
+<span class="sd"> json_projection: a json document indicating the fields that appear in the results</span>
+
+<span class="sd"> Returns:</span>
+<span class="sd"> doc_json: a json document or None</span>
+<span class="sd"> """</span>
+ <span class="n">results</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">near</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">collection_neighbourhoods</span><span class="p">,</span> <span class="n">coordinates</span><span class="p">,</span> <span class="n">json_projection</span><span class="p">,</span> <span class="mi">1</span><span class="p">)</span> <span class="c1"># distance = 1 meter</span>
+ <span class="k">if</span> <span class="nb">len</span><span class="p">(</span><span class="n">results</span><span class="p">)</span> <span class="o">==</span> <span class="mi">0</span><span class="p">:</span>
+ <span class="k">return</span> <span class="kc">None</span>
+ <span class="k">return</span> <span class="n">results</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span>
+
+ <span class="k">def</span> <span class="nf">near</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">collection</span><span class="p">,</span> <span class="n">coordinates</span><span class="p">,</span> <span class="n">json_projection</span><span class="o">=</span><span class="kc">None</span><span class="p">,</span> <span class="n">distance_max</span><span class="o">=</span><span class="mi">2000</span><span class="p">):</span>
+ <span class="sd">"""</span>
+<span class="sd"> Finds all documents from given collection and which are near the given geometry (according to distance_max).</span>
+
+<span class="sd"> Args:</span>
+<span class="sd"> collection: a string representing the collection name</span>
+<span class="sd"> coordinates: an array of coordinates (long, lat) - near only accepts Point</span>
+<span class="sd"> json_projection: a json document indicating the fields that appear in the results</span>
+<span class="sd"> distance_max: the maximum distance of resulting iris, in meters</span>
+
+<span class="sd"> Returns:</span>
+<span class="sd"> doc_json: a cursor (set of documents)</span>
+<span class="sd"> """</span>
+ <span class="n">geometry</span> <span class="o">=</span> <span class="n">Mongiris</span><span class="o">.</span><span class="n">get_geojson_point</span><span class="p">(</span><span class="n">coordinates</span><span class="p">)</span>
+ <span class="n">cursor</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">find_documents</span><span class="p">(</span><span class="n">collection</span><span class="p">,</span> <span class="p">{</span><span class="s2">"geometry"</span><span class="p">:</span> <span class="p">{</span><span class="s2">"$near"</span><span class="p">:</span> <span class="p">{</span>
+ <span class="s2">"$geometry"</span><span class="p">:</span> <span class="n">geometry</span><span class="p">,</span> <span class="s2">"$maxDistance"</span><span class="p">:</span> <span class="n">distance_max</span><span class="p">}}},</span> <span class="n">json_projection</span><span class="p">)</span>
+ <span class="n">doc_json</span> <span class="o">=</span> <span class="n">Mongiris</span><span class="o">.</span><span class="n">bson_to_json</span><span class="p">(</span><span class="n">cursor</span><span class="p">)</span>
+ <span class="k">return</span> <span class="n">doc_json</span>
+
+ <span class="nd">@staticmethod</span>
+ <span class="k">def</span> <span class="nf">adjacent</span><span class="p">(</span><span class="n">collection</span><span class="p">,</span> <span class="n">geometry</span><span class="p">,</span> <span class="n">json_projection</span><span class="o">=</span><span class="kc">None</span><span class="p">,</span> <span class="n">distance</span><span class="o">=</span><span class="mi">20</span><span class="p">,</span> <span class="n">exclude_geometry</span><span class="o">=</span><span class="kc">None</span><span class="p">):</span>
+ <span class="sd">"""</span>
+<span class="sd"> Finds all adjacent neighbors of a neighbourhood represented by geometry.</span>
+<span class="sd"> No adjacent function, so use all coordinates of an iris and find the closest neighbourhood (according to</span>
+<span class="sd"> distance). Could be done directly with near(), but near() is less accurate and thus incomplete.</span>
+
+<span class="sd"> Args:</span>
+<span class="sd"> collection: a string representing the collection name</span>
+<span class="sd"> geometry: a geojson geometry (Point, Polygon, etc.)</span>
+<span class="sd"> json_projection: a json document indicating the fields that appear in the results</span>
+<span class="sd"> distance: the maximum distance for an adjacent neighbour, in meters (10 to 50 meters are fine)</span>
+<span class="sd"> exclude_geometry: the document _id of the neighbourhood represented by geometry, if it needs to be excluded</span>
+
+<span class="sd"> Returns:</span>
+<span class="sd"> doc_json: a cursor (set of documents)</span>
+<span class="sd"> """</span>
+ <span class="n">results</span> <span class="o">=</span> <span class="nb">list</span><span class="p">()</span>
+ <span class="n">results_ids</span> <span class="o">=</span> <span class="nb">list</span><span class="p">()</span>
+ <span class="k">if</span> <span class="n">exclude_geometry</span> <span class="ow">is</span> <span class="ow">not</span> <span class="kc">None</span><span class="p">:</span> <span class="c1"># to exclude the neighbourhood represented by geometry, add it to the results ids</span>
+ <span class="n">results_ids</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="n">exclude_geometry</span><span class="p">)</span>
+ <span class="k">for</span> <span class="n">coords</span> <span class="ow">in</span> <span class="n">geometry</span><span class="p">[</span><span class="s2">"coordinates"</span><span class="p">][</span><span class="mi">0</span><span class="p">]:</span>
+ <span class="n">geometry_coords</span> <span class="o">=</span> <span class="n">Mongiris</span><span class="o">.</span><span class="n">get_geojson_point</span><span class="p">(</span><span class="n">coords</span><span class="p">)</span>
+ <span class="n">cursor</span> <span class="o">=</span> <span class="n">collection</span><span class="o">.</span><span class="n">find</span><span class="p">({</span><span class="s2">"geometry"</span><span class="p">:</span> <span class="p">{</span><span class="s2">"$near"</span><span class="p">:</span> <span class="p">{</span><span class="s2">"$geometry"</span><span class="p">:</span> <span class="n">geometry_coords</span><span class="p">,</span>
+ <span class="s2">"$maxDistance"</span><span class="p">:</span> <span class="n">distance</span><span class="p">}}},</span> <span class="n">json_projection</span><span class="p">)</span>
+ <span class="k">for</span> <span class="n">doc</span> <span class="ow">in</span> <span class="n">cursor</span><span class="p">:</span>
+ <span class="n">doc_id</span> <span class="o">=</span> <span class="n">doc</span><span class="p">[</span><span class="s2">"_id"</span><span class="p">]</span>
+ <span class="k">if</span> <span class="n">doc_id</span> <span class="ow">not</span> <span class="ow">in</span> <span class="n">results_ids</span><span class="p">:</span> <span class="c1"># add the new adjacent iris if not already in the results</span>
+ <span class="n">results</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="n">doc</span><span class="p">)</span>
+ <span class="n">results_ids</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="n">doc_id</span><span class="p">)</span>
+ <span class="n">doc_json</span> <span class="o">=</span> <span class="n">Mongiris</span><span class="o">.</span><span class="n">bson_to_json</span><span class="p">(</span><span class="n">results</span><span class="p">)</span>
+ <span class="k">return</span> <span class="n">doc_json</span>
+</pre></div>
+
+ </details>
+
+ <div class="docstring"><p>The Mongiris class is an API to manipulate data from a MongoDB database containing neighbourhoods (GeoJSON format).</p>
+
<p>Several methods accepts a 'collection' parameter for flexibility (i.e., be able to query other collections than the
-iris collection).
+neighbourhoods collection).
Most methods convert resulting documents from the BSON format (MongoDB) to JSON. This mainly avoids the issue of
ObjectId type (for MongoDB '_id' field).</p>
+
<p>The constructor initializes the logger and it automatically connects to the database.
The name of the database and of the three collections
are based on the default names (the ones from the dump). If the names are changed in MongoDB, they should be changed
in the <code>config.py</code> file.</p>
+
<p>Examples of usages, including testing geospatial queries, are available in <code>tests/api_tests.py</code>.</p>
-<p>An example of IRIS following the GeoJSON format is provided in <code>data/example-iris.json</code>.</p>
+
+<p>An example of neighbourhood following the GeoJSON format is provided in <code>data/example-neighbourhood.json</code>.</p>
+
+<p>Args:
+ host: the server hosting MongoDB (string, default to 'localhost')
+ port: the port number on which MongoDB listens to (integer, default tp 27017)
+ db: the MongoDB database name to connect to (string)
+ coll_neighbourhoods: the name of the neighbourhoods collection, inside database db (string)
+ coll_indic: the name of the indicators collection, inside database db (string)</p>
+
<p>Additional resources:</p>
+
<ul>
-<li>
-<p><a href="http://www.mongodb.org/">MongoDB documentation</a></p>
-</li>
-<li>
-<p><a href="https://geojson.org/">GeoJSON format specifications</a></p>
-</li>
-<li>
-<p><a href="http://api.mongodb.com/python/current/">pymongo API</a> between Python and MongoDB</p>
-</li>
-</ul></section>
-<details class="source">
-<summary>Source code</summary>
-<pre><code class="python">class Mongiris:
- """
- The Mongiris class is an API to manipulate data from the MongoDB `dbinsee` datatase.
-
- Several methods accepts a 'collection' parameter for flexibility (i.e., be able to query other collections than the
- iris collection).
- Most methods convert resulting documents from the BSON format (MongoDB) to JSON. This mainly avoids the issue of
- ObjectId type (for MongoDB '_id' field).
-
- The constructor initializes the logger and it automatically connects to the database.
- The name of the database and of the three collections
- are based on the default names (the ones from the dump). If the names are changed in MongoDB, they should be changed
- in the `config.py` file.
-
- Examples of usages, including testing geospatial queries, are available in `tests/api_tests.py`.
-
- An example of IRIS following the GeoJSON format is provided in `data/example-iris.json`.
-
- Additional resources:
-
- - [MongoDB documentation](http://www.mongodb.org/)
-
- - [GeoJSON format specifications](https://geojson.org/)
-
- - [pymongo API](http://api.mongodb.com/python/current/) between Python and MongoDB
-
- """
-
- def __init__(self):
- logging.basicConfig(format='[%(levelname)s] - %(name)s - %(asctime)s : %(message)s')
- self.logger = logging.getLogger()
- self.logger.setLevel(logging.INFO)
- self.connection, self.connection_status = self.init_connection() # default connection on 'localhost', 27017
- self.database = self.connection[config.database_iris] # database for HiL project
- self.collection_iris = self.database[config.collection_iris]
- self.collection_indic = self.database[config.collection_indic]
- self.collection_sources = self.database[config.collection_sources]
-
- @staticmethod
- def bson_to_json(doc_bson):
- """
- Converts the bson data to valid JSON (including the ObjectId type converted to {"$oid": <string>}).
-
- Args:
- doc_bson: the BSON data to be converted
-
- Returns:
- doc_json: a JSON object
- """
- doc_json = json.loads(json_util.dumps(doc_bson, json_options=json_util.RELAXED_JSON_OPTIONS))
- return doc_json
-
- def init_connection(self):
- """
- Tries to connect to MongoDB. The output connection object do not provide reliable connection status, only the
- boolean connection_status indicates whether the connection is working or not.
-
- Returns:
- connection: an object with information about the connection
- connection_status: a boolean indicating whether the connection is a success or a failure
- """
- connection_status = True # by default, connection is ok
- connection = None
- try:
- connection = pymongo.MongoClient(serverSelectionTimeoutMS=config.max_timeout) # default localhost:27017
- connection.server_info() # forces a query to MongoDB (for checking the connection)
- except pymongo.errors.ServerSelectionTimeoutError as e:
- self.logger.error('Could not connect to the MongoDB database ! Have you launched MongoDB ? ' + str(e))
- connection_status = False
- return connection, connection_status
-
- @staticmethod
- def _parse_json_to_dict(json_file_path):
- """ Converts a JSON file denoted by json_file_path into a Python dictionary. """
- with open(json_file_path) as data_file:
- data = json.load(data_file)
- data_file.close()
- return data
-
- @staticmethod
- def _save_dict_to_json(json_file_path, dict_geo):
- """ Converts and saves a Python dictionary into a JSON file denoted by json_file_path. """
- with open(json_file_path, 'w') as data_file:
- json.dump(dict_geo, data_file)
-
- def create_index(self, iris_collection):
- """ Rebuilds a geospatial index on the iris collection. Only used in case of restoration/import. """
- self.logger.info("Creating index on 'geometry' using " + pymongo.GEOSPHERE)
- iris_collection.create_index([("geometry", pymongo.GEOSPHERE)])
- self.logger.info("Index created")
-
- def count_documents(self, collection, json_query):
- """
- Counts the number of documents that satisfy json_query in the given collection.
-
- Args:
- collection: a string representing the collection name
- json_query: a dict containing the query criteria (https://docs.mongodb.com/manual/tutorial/query-documents/)
-
- Returns:
- count: an integer representing the number of documents
- """
- return collection.count_documents(json_query)
-
- def find_one_document(self, collection, json_query):
- """
- Finds the first document in the given collection that satisfies json_query.
-
- Args:
- collection: a string representing the collection name
- json_query: a dict containing the query criteria (https://docs.mongodb.com/manual/tutorial/query-documents/)
-
- Returns:
- doc_json: a dictionary representing an iris, or None
- """
- doc = collection.find_one(json_query)
- doc_json = Mongiris.bson_to_json(doc)
- return doc_json
-
- def get_iris_from_code(self, code_iris):
- """
- Returns the iris identified by the given code_iris.
-
- Args:
- code_iris: a string containing the code of the searched iris
-
- Returns:
- iris: a dictionary representing an iris, or None
- """
- iris = self.find_one_document(self.collection_iris, {"properties.CODE_IRIS": code_iris})
- return iris
-
- def find_documents(self, collection, json_query, json_projection=None):
- """
- Finds the first document in the given collection that satisfies json_query.
-
- Args:
- collection: a string representing the collection name
- json_query: a dict containing the query criteria (https://docs.mongodb.com/manual/tutorial/query-documents/)
- json_projection: a json document indicating the fields that appear in the results
-
- Returns:
- doc_json: a cursor (set of documents)
- """
- cursor = collection.find(json_query, json_projection)
- doc_json = Mongiris.bson_to_json(cursor)
- return doc_json
-
- def get_random_document(self, collection):
- """ Returns a random document from the given collection. """
- random_iris = collection.aggregate([{"$sample": {"size": 1}}]).next()
- doc_json = Mongiris.bson_to_json(random_iris)
- return doc_json
-
- def update_one_document(self, collection, json_query, json_updates):
- """
- Updates the first document satisfying json_query by setting new values from json_updates.
-
- Args:
- collection: a string representing the collection name
- json_query: a dict containing the query criteria (https://docs.mongodb.com/manual/tutorial/query-documents/)
- json_updates: a json document containing values to be updates (using $set operator)
-
- Returns:
- json_result: an UpdateResult json document containing information about the operation
- """
- json_result = collection.update_one(json_query, json_updates)
- return json_result
-
- def replace_one_document(self, collection, json_query, json_replace_doc, upsert=False):
- """
- Replaces the first document satisfying json_query by the document json_replace_doc (their _id are identical).
-
- Args:
- collection: a string representing the collection name
- json_query: a dict containing the query criteria (https://docs.mongodb.com/manual/tutorial/query-documents/)
- json_replace_doc: the replacement doc (if _id set, should be the same _id as the doc matching json_query)
- upsert: a boolean, whether the json_replace_doc should be inserted if no document match json_query
-
- Returns:
- json_result: an UpdateResult json document containing information about the operation
- """
- json_result = collection.replace_one(json_query, json_replace_doc, upsert)
- return json_result
-
- def insert_one_document(self, collection, doc):
- """
- Inserts a new document in the collection.
-
- Args:
- collection: a string representing the collection name
- doc: a dict representing the document to be added
-
- Returns:
- json_result: an InsertOneResult json document containing information about the operation
- """
- json_result = collection.insert_one(doc)
- return json_result # eg, the new _id is in json_result.inserted_id
-
- def delete_all(self, collection):
- """
- Deletes all documents in the collection.
-
- Args:
- collection: a string representing the collection name
-
- Returns:
- json_result: an DeleteResult json document containing information about the operation
- """
- json_result = collection.delete_many({}) # empty collection
- return json_result
-
- def geo_within(self, collection, geometry, json_projection=None):
- """
- Finds all documents from given collection and which contain totally the given geometry.
- Cannot be used to find the IRIS containing a point (geometry must be a polygon).
-
- Args:
- collection: a string representing the collection name
- geometry: a geojson geometry ("Polygon", "$box" or "MultiPolygon", NO "Point")
- json_projection: a json document indicating the fields that appear in the results
-
- Returns:
- doc_json: a cursor (set of documents)
- """
- cursor = self.find_documents(collection, {"geometry": {"$geoWithin": {"$geometry": geometry}}}, json_projection)
- doc_json = Mongiris.bson_to_json(cursor)
- return doc_json
-
- def geo_within_sphere(self, collection, sphere, json_projection=None):
- """
- Finds all documents from given collection and which contain totally the given sphere.
- Cannot be used to find the IRIS containing a point (geometry must be a polygon, with min. 3 points).
-
- Args:
- collection: a string representing the collection name
- sphere: a geojson geometry defined by a center and a radius in radians
- json_projection: a json document indicating the fields that appear in the results
-
- Returns:
- doc_json: a cursor (set of documents)
- """
- cursor = self.find_documents(collection, {"geometry": {"$geoWithin": sphere}}, json_projection)
- doc_json = Mongiris.bson_to_json(cursor)
- return doc_json
-
- def intersect(self, collection, geometry, json_projection=None):
- """
- Finds all documents from given collection and which intersect the given geometry.
-
- Args:
- collection: a string representing the collection name
- geometry: a geojson geometry
- json_projection: a json document indicating the fields that appear in the results
-
- Returns:
- doc_json: a cursor (set of documents)
- """
- cursor = self.find_documents(collection, {"geometry": {"$geoIntersects": {
- "$geometry": geometry}}}, json_projection)
- doc_json = Mongiris.bson_to_json(cursor)
- return doc_json
-
- @staticmethod
- def get_geojson_point(coordinates):
- """
- Builds a dictionary with GeoJSON syntax for a point using the given coordinates.
-
- Args:
- coordinates: the coordinates (long, lat) as a list, e.g. [4.8, 45.7]
-
- Returns:
- point: a dictionary with GeoJSON syntax for a Point
- """
- return {"type": "Point", "coordinates": coordinates}
-
- @staticmethod
- def convert_geojson_box_to_polygon(lng1, lat1, lng2, lat2):
- """
- Builds a dictionary with GeoJSON syntax for a polygon using two coordinates (points south-west and north-east).
- This method builds the polygon by adding 2 missing points (north-west and south-east) and adds the starting
- point (south-west) to end the loop.
- The MongoDB $box operator is not supported with 2d-spherical indexes.
-
- Args:
- lng1: longitude of the first point (south-west) of the box
- lat1: latitude of the first point (south-west) of the box
- lng2: longitude of the second point (north-east) of the box
- lat2: latitude of the second point (north-east) of the box
-
- Returns:
- box: a dictionary with GeoJSON syntax for a Box
- """
- coordinates = [[[lng1, lat1], [lng1, lat2], [lng2, lat2], [lng2, lat1], [lng1, lat1]]]
- return Mongiris.get_geojson_polygon(coordinates)
-
- @staticmethod
- def get_geojson_polygon(coordinates):
- """
- Builds a dictionary with GeoJSON syntax for a polygon using the given coordinates.
- Careful: polygons must be closed ! (first coordinate must be identical to last coordinate)
-
- Args:
- coordinates: the coordinates (long, lat) as a list of list, e.g. [[[4.8, 45.7], [4.9, 47.8]]]
-
- Returns:
- polygon: a dictionary with GeoJSON syntax for a Polygon
- """
- return {"type": "Polygon", "coordinates": coordinates}
-
- def point_in_which_iris(self, coordinates, json_projection=None):
- """
- Finds the document (IRIS) containing the given coordinates. Uses near() since geo_within() requires a Polygon.
- Careful: the near() operator may return several iris (low probability since distance = 1 meter) and only the
- first one is returned.
-
- Args:
- coordinates: an array of coordinates (long, lat)
- json_projection: a json document indicating the fields that appear in the results
-
- Returns:
- doc_json: a json document or None
- """
- results = self.near(self.collection_iris, coordinates, json_projection, 1) # distance = 1 meter
- if len(results) == 0:
- return None
- return results[0]
-
- def near(self, collection, coordinates, json_projection=None, distance_max=2000):
- """
- Finds all documents from given collection and which are near the given geometry (according to distance_max).
-
- Args:
- collection: a string representing the collection name
- coordinates: an array of coordinates (long, lat) - near only accepts Point
- json_projection: a json document indicating the fields that appear in the results
- distance_max: the maximum distance of resulting iris, in meters
-
- Returns:
- doc_json: a cursor (set of documents)
- """
- geometry = Mongiris.get_geojson_point(coordinates)
- cursor = self.find_documents(collection, {"geometry": {"$near": {
- "$geometry": geometry, "$maxDistance": distance_max}}}, json_projection)
- doc_json = Mongiris.bson_to_json(cursor)
- return doc_json
-
- @staticmethod
- def adjacent(collection, geometry, json_projection=None, distance=20, exclude_geometry_iris=None):
- """
- Finds all adjacent neighbors of an iris represented by geometry.
- No adjacent function, so use all coordinates of an iris and find the closest iris (according to distance).
- Could be done directly with near(), but near() is less accurate and thus incomplete.
-
- Args:
- collection: a string representing the collection name
- geometry: a geojson geometry (Point, Polygon, etc.)
- json_projection: a json document indicating the fields that appear in the results
- distance: the maximum distance for an adjacent neighbour, in meters (10 to 50 meters are fine)
- exclude_geometry_iris: the document _id of the iris represented by geometry, if it needs to be excluded
-
- Returns:
- doc_json: a cursor (set of documents)
- """
- results = list()
- results_ids = list()
- if exclude_geometry_iris is not None: # to exclude the iris represented by geometry, add it to the results ids
- results_ids.append(exclude_geometry_iris)
- for coords in geometry["coordinates"][0]:
- geometry_coords = Mongiris.get_geojson_point(coords)
- cursor = collection.find({"geometry": {"$near": {"$geometry": geometry_coords,
- "$maxDistance": distance}}}, json_projection)
- for doc in cursor:
- doc_id = doc["_id"]
- if doc_id not in results_ids: # add the new adjacent iris if not already in the results
- results.append(doc)
- results_ids.append(doc_id)
- doc_json = Mongiris.bson_to_json(results)
- return doc_json</code></pre>
-</details>
-<h3>Static methods</h3>
-<dl>
-<dt id="api.Mongiris.adjacent"><code class="name flex">
-<span>def <span class="ident">adjacent</span></span>(<span>collection, geometry, json_projection=None, distance=20, exclude_geometry_iris=None)</span>
-</code></dt>
-<dd>
-<section class="desc"><p>Finds all adjacent neighbors of an iris represented by geometry.
-No adjacent function, so use all coordinates of an iris and find the closest iris (according to distance).
-Could be done directly with near(), but near() is less accurate and thus incomplete.</p>
-<h2 id="args">Args</h2>
-<dl>
-<dt><strong><code>collection</code></strong></dt>
-<dd>a string representing the collection name</dd>
-<dt><strong><code>geometry</code></strong></dt>
-<dd>a geojson geometry (Point, Polygon, etc.)</dd>
-<dt><strong><code>json_projection</code></strong></dt>
-<dd>a json document indicating the fields that appear in the results</dd>
-<dt><strong><code>distance</code></strong></dt>
-<dd>the maximum distance for an adjacent neighbour, in meters (10 to 50 meters are fine)</dd>
-<dt><strong><code>exclude_geometry_iris</code></strong></dt>
-<dd>the document _id of the iris represented by geometry, if it needs to be excluded</dd>
-</dl>
-<h2 id="returns">Returns</h2>
-<dl>
-<dt><strong><code>doc_json</code></strong></dt>
-<dd>a cursor (set of documents)</dd>
-</dl></section>
-<details class="source">
-<summary>Source code</summary>
-<pre><code class="python">@staticmethod
-def adjacent(collection, geometry, json_projection=None, distance=20, exclude_geometry_iris=None):
- """
- Finds all adjacent neighbors of an iris represented by geometry.
- No adjacent function, so use all coordinates of an iris and find the closest iris (according to distance).
- Could be done directly with near(), but near() is less accurate and thus incomplete.
-
- Args:
- collection: a string representing the collection name
- geometry: a geojson geometry (Point, Polygon, etc.)
- json_projection: a json document indicating the fields that appear in the results
- distance: the maximum distance for an adjacent neighbour, in meters (10 to 50 meters are fine)
- exclude_geometry_iris: the document _id of the iris represented by geometry, if it needs to be excluded
-
- Returns:
- doc_json: a cursor (set of documents)
- """
- results = list()
- results_ids = list()
- if exclude_geometry_iris is not None: # to exclude the iris represented by geometry, add it to the results ids
- results_ids.append(exclude_geometry_iris)
- for coords in geometry["coordinates"][0]:
- geometry_coords = Mongiris.get_geojson_point(coords)
- cursor = collection.find({"geometry": {"$near": {"$geometry": geometry_coords,
- "$maxDistance": distance}}}, json_projection)
- for doc in cursor:
- doc_id = doc["_id"]
- if doc_id not in results_ids: # add the new adjacent iris if not already in the results
- results.append(doc)
- results_ids.append(doc_id)
- doc_json = Mongiris.bson_to_json(results)
- return doc_json</code></pre>
-</details>
-</dd>
-<dt id="api.Mongiris.bson_to_json"><code class="name flex">
-<span>def <span class="ident">bson_to_json</span></span>(<span>doc_bson)</span>
-</code></dt>
-<dd>
-<section class="desc"><p>Converts the bson data to valid JSON (including the ObjectId type converted to {"$oid": <string>}).</p>
-<h2 id="args">Args</h2>
-<dl>
-<dt><strong><code>doc_bson</code></strong></dt>
-<dd>the BSON data to be converted</dd>
-</dl>
-<h2 id="returns">Returns</h2>
-<dl>
-<dt><strong><code>doc_json</code></strong></dt>
-<dd>a JSON object</dd>
-</dl></section>
-<details class="source">
-<summary>Source code</summary>
-<pre><code class="python">@staticmethod
-def bson_to_json(doc_bson):
- """
- Converts the bson data to valid JSON (including the ObjectId type converted to {"$oid": <string>}).
-
- Args:
- doc_bson: the BSON data to be converted
-
- Returns:
- doc_json: a JSON object
- """
- doc_json = json.loads(json_util.dumps(doc_bson, json_options=json_util.RELAXED_JSON_OPTIONS))
- return doc_json</code></pre>
-</details>
-</dd>
-<dt id="api.Mongiris.convert_geojson_box_to_polygon"><code class="name flex">
-<span>def <span class="ident">convert_geojson_box_to_polygon</span></span>(<span>lng1, lat1, lng2, lat2)</span>
-</code></dt>
-<dd>
-<section class="desc"><p>Builds a dictionary with GeoJSON syntax for a polygon using two coordinates (points south-west and north-east).
+<li><p><a href="http://www.mongodb.org/">MongoDB documentation</a></p></li>
+<li><p><a href="https://geojson.org/">GeoJSON format specifications</a></p></li>
+<li><p><a href="http://api.mongodb.com/python/current/">pymongo API</a> between Python and MongoDB</p></li>
+</ul>
+</div>
+
+
+ <div id="Mongiris.__init__" class="classattr">
+ <div class="attr function"><a class="headerlink" href="#Mongiris.__init__">#  </a>
+
+
+ <span class="name">Mongiris</span><span class="signature">(
+ self,
+ host='localhost',
+ port=27017,
+ db='dbinsee',
+ coll_neighbourhoods='colliris',
+ coll_indic='collindic'
+)</span> </div>
+
+ <details>
+ <summary>View Source</summary>
+ <div class="codehilite"><pre><span></span> <span class="k">def</span> <span class="fm">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">host</span><span class="o">=</span><span class="s1">'localhost'</span><span class="p">,</span> <span class="n">port</span><span class="o">=</span><span class="mi">27017</span><span class="p">,</span> <span class="n">db</span><span class="o">=</span><span class="s1">'dbinsee'</span><span class="p">,</span> <span class="n">coll_neighbourhoods</span><span class="o">=</span><span class="s1">'colliris'</span><span class="p">,</span> <span class="n">coll_indic</span><span class="o">=</span><span class="s1">'collindic'</span><span class="p">):</span>
+ <span class="n">logging</span><span class="o">.</span><span class="n">basicConfig</span><span class="p">(</span><span class="nb">format</span><span class="o">=</span><span class="s1">'[</span><span class="si">%(levelname)s</span><span class="s1">] - </span><span class="si">%(name)s</span><span class="s1"> - </span><span class="si">%(asctime)s</span><span class="s1"> : </span><span class="si">%(message)s</span><span class="s1">'</span><span class="p">)</span>
+ <span class="bp">self</span><span class="o">.</span><span class="n">logger</span> <span class="o">=</span> <span class="n">logging</span><span class="o">.</span><span class="n">getLogger</span><span class="p">()</span>
+ <span class="bp">self</span><span class="o">.</span><span class="n">logger</span><span class="o">.</span><span class="n">setLevel</span><span class="p">(</span><span class="n">logging</span><span class="o">.</span><span class="n">INFO</span><span class="p">)</span>
+ <span class="bp">self</span><span class="o">.</span><span class="n">host</span> <span class="o">=</span> <span class="n">host</span>
+ <span class="bp">self</span><span class="o">.</span><span class="n">port</span> <span class="o">=</span> <span class="n">port</span>
+ <span class="bp">self</span><span class="o">.</span><span class="n">connection</span><span class="p">,</span> <span class="bp">self</span><span class="o">.</span><span class="n">connection_status</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">init_connection</span><span class="p">()</span>
+ <span class="bp">self</span><span class="o">.</span><span class="n">dbname</span> <span class="o">=</span> <span class="n">db</span>
+ <span class="bp">self</span><span class="o">.</span><span class="n">database</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">connection</span><span class="p">[</span><span class="n">db</span><span class="p">]</span> <span class="c1"># link to database</span>
+ <span class="bp">self</span><span class="o">.</span><span class="n">collection_neighbourhoods</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">database</span><span class="p">[</span><span class="n">coll_neighbourhoods</span><span class="p">]</span> <span class="c1"># link to neighbourhoods collection</span>
+ <span class="bp">self</span><span class="o">.</span><span class="n">collection_indicators</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">database</span><span class="p">[</span><span class="n">coll_indic</span><span class="p">]</span> <span class="c1"># link to indicators collection (used for prediction)</span>
+</pre></div>
+
+ </details>
+
+
+
+ </div>
+ <div id="Mongiris.bson_to_json" class="classattr">
+ <div class="attr function"><a class="headerlink" href="#Mongiris.bson_to_json">#  </a>
+
+ <div class="decorator">@staticmethod</div>
+
+ <span class="def">def</span>
+ <span class="name">bson_to_json</span><span class="signature">(doc_bson)</span>:
+ </div>
+
+ <details>
+ <summary>View Source</summary>
+ <div class="codehilite"><pre><span></span> <span class="nd">@staticmethod</span>
+ <span class="k">def</span> <span class="nf">bson_to_json</span><span class="p">(</span><span class="n">doc_bson</span><span class="p">):</span>
+ <span class="sd">"""</span>
+<span class="sd"> Converts the bson data to valid JSON (including the ObjectId type converted to {"$oid": <string>}).</span>
+
+<span class="sd"> Args:</span>
+<span class="sd"> doc_bson: the BSON data to be converted</span>
+
+<span class="sd"> Returns:</span>
+<span class="sd"> doc_json: a JSON object</span>
+<span class="sd"> """</span>
+ <span class="n">doc_json</span> <span class="o">=</span> <span class="n">json</span><span class="o">.</span><span class="n">loads</span><span class="p">(</span><span class="n">json_util</span><span class="o">.</span><span class="n">dumps</span><span class="p">(</span><span class="n">doc_bson</span><span class="p">,</span> <span class="n">json_options</span><span class="o">=</span><span class="n">json_util</span><span class="o">.</span><span class="n">RELAXED_JSON_OPTIONS</span><span class="p">))</span>
+ <span class="k">return</span> <span class="n">doc_json</span>
+</pre></div>
+
+ </details>
+
+ <div class="docstring"><p>Converts the bson data to valid JSON (including the ObjectId type converted to {"$oid": <string>}).</p>
+
+<p>Args:
+ doc_bson: the BSON data to be converted</p>
+
+<p>Returns:
+ doc_json: a JSON object</p>
+</div>
+
+
+ </div>
+ <div id="Mongiris.init_connection" class="classattr">
+ <div class="attr function"><a class="headerlink" href="#Mongiris.init_connection">#  </a>
+
+
+ <span class="def">def</span>
+ <span class="name">init_connection</span><span class="signature">(self)</span>:
+ </div>
+
+ <details>
+ <summary>View Source</summary>
+ <div class="codehilite"><pre><span></span> <span class="k">def</span> <span class="nf">init_connection</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
+ <span class="sd">"""</span>
+<span class="sd"> Tries to connect to MongoDB (default on localhost:27017). The output connection object do not provide </span>
+<span class="sd"> reliable connection status, only the boolean connection_status indicates whether the connection is </span>
+<span class="sd"> working or not.</span>
+
+<span class="sd"> Returns:</span>
+<span class="sd"> connection: an object with information about the connection</span>
+<span class="sd"> connection_status: a boolean indicating whether the connection is a success or a failure</span>
+<span class="sd"> """</span>
+ <span class="n">connection_status</span> <span class="o">=</span> <span class="kc">True</span> <span class="c1"># by default, connection is ok</span>
+ <span class="n">connection</span> <span class="o">=</span> <span class="kc">None</span>
+ <span class="bp">self</span><span class="o">.</span><span class="n">logger</span><span class="o">.</span><span class="n">info</span><span class="p">(</span><span class="sa">f</span><span class="s1">'Trying to connect to MongoDB server (</span><span class="si">{</span><span class="bp">self</span><span class="o">.</span><span class="n">host</span><span class="si">}</span><span class="s1">:</span><span class="si">{</span><span class="bp">self</span><span class="o">.</span><span class="n">port</span><span class="si">}</span><span class="s1">)...'</span><span class="p">)</span>
+ <span class="k">try</span><span class="p">:</span>
+ <span class="n">connection</span> <span class="o">=</span> <span class="n">pymongo</span><span class="o">.</span><span class="n">MongoClient</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">host</span><span class="p">,</span> <span class="bp">self</span><span class="o">.</span><span class="n">port</span><span class="p">,</span> <span class="n">serverSelectionTimeoutMS</span><span class="o">=</span><span class="n">max_timeout</span><span class="p">)</span>
+ <span class="n">connection</span><span class="o">.</span><span class="n">server_info</span><span class="p">()</span> <span class="c1"># forces a query to MongoDB (for checking the connection)</span>
+ <span class="k">except</span> <span class="n">pymongo</span><span class="o">.</span><span class="n">errors</span><span class="o">.</span><span class="n">ServerSelectionTimeoutError</span> <span class="k">as</span> <span class="n">e</span><span class="p">:</span>
+ <span class="bp">self</span><span class="o">.</span><span class="n">logger</span><span class="o">.</span><span class="n">error</span><span class="p">(</span><span class="s1">'Could not connect to the MongoDB database ! Have you launched MongoDB ? '</span> <span class="o">+</span> <span class="nb">str</span><span class="p">(</span><span class="n">e</span><span class="p">))</span>
+ <span class="n">connection_status</span> <span class="o">=</span> <span class="kc">False</span>
+ <span class="k">return</span> <span class="n">connection</span><span class="p">,</span> <span class="n">connection_status</span>
+</pre></div>
+
+ </details>
+
+ <div class="docstring"><p>Tries to connect to MongoDB (default on localhost:27017). The output connection object do not provide
+reliable connection status, only the boolean connection_status indicates whether the connection is
+working or not.</p>
+
+<p>Returns:
+ connection: an object with information about the connection
+ connection_status: a boolean indicating whether the connection is a success or a failure</p>
+</div>
+
+
+ </div>
+ <div id="Mongiris.create_index" class="classattr">
+ <div class="attr function"><a class="headerlink" href="#Mongiris.create_index">#  </a>
+
+
+ <span class="def">def</span>
+ <span class="name">create_index</span><span class="signature">(self, iris_collection)</span>:
+ </div>
+
+ <details>
+ <summary>View Source</summary>
+ <div class="codehilite"><pre><span></span> <span class="k">def</span> <span class="nf">create_index</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">iris_collection</span><span class="p">):</span>
+ <span class="sd">""" Rebuilds a geospatial index on the iris collection. Only used in case of restoration/import. """</span>
+ <span class="bp">self</span><span class="o">.</span><span class="n">logger</span><span class="o">.</span><span class="n">info</span><span class="p">(</span><span class="s2">"Creating index on 'geometry' using "</span> <span class="o">+</span> <span class="n">pymongo</span><span class="o">.</span><span class="n">GEOSPHERE</span><span class="p">)</span>
+ <span class="n">iris_collection</span><span class="o">.</span><span class="n">create_index</span><span class="p">([(</span><span class="s2">"geometry"</span><span class="p">,</span> <span class="n">pymongo</span><span class="o">.</span><span class="n">GEOSPHERE</span><span class="p">)])</span>
+ <span class="bp">self</span><span class="o">.</span><span class="n">logger</span><span class="o">.</span><span class="n">info</span><span class="p">(</span><span class="s2">"Index created"</span><span class="p">)</span>
+</pre></div>
+
+ </details>
+
+ <div class="docstring"><p>Rebuilds a geospatial index on the iris collection. Only used in case of restoration/import.</p>
+</div>
+
+
+ </div>
+ <div id="Mongiris.count_documents" class="classattr">
+ <div class="attr function"><a class="headerlink" href="#Mongiris.count_documents">#  </a>
+
+
+ <span class="def">def</span>
+ <span class="name">count_documents</span><span class="signature">(self, collection, json_query)</span>:
+ </div>
+
+ <details>
+ <summary>View Source</summary>
+ <div class="codehilite"><pre><span></span> <span class="k">def</span> <span class="nf">count_documents</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">collection</span><span class="p">,</span> <span class="n">json_query</span><span class="p">):</span>
+ <span class="sd">"""</span>
+<span class="sd"> Counts the number of documents that satisfy json_query in the given collection.</span>
+
+<span class="sd"> Args:</span>
+<span class="sd"> collection: a string representing the collection name</span>
+<span class="sd"> json_query: a dict containing the query criteria (https://docs.mongodb.com/manual/tutorial/query-documents/)</span>
+
+<span class="sd"> Returns:</span>
+<span class="sd"> count: an integer representing the number of documents</span>
+<span class="sd"> """</span>
+ <span class="k">return</span> <span class="n">collection</span><span class="o">.</span><span class="n">count_documents</span><span class="p">(</span><span class="n">json_query</span><span class="p">)</span>
+</pre></div>
+
+ </details>
+
+ <div class="docstring"><p>Counts the number of documents that satisfy json_query in the given collection.</p>
+
+<p>Args:
+ collection: a string representing the collection name
+ json_query: a dict containing the query criteria (https://docs.mongodb.com/manual/tutorial/query-documents/)</p>
+
+<p>Returns:
+ count: an integer representing the number of documents</p>
+</div>
+
+
+ </div>
+ <div id="Mongiris.find_one_document" class="classattr">
+ <div class="attr function"><a class="headerlink" href="#Mongiris.find_one_document">#  </a>
+
+
+ <span class="def">def</span>
+ <span class="name">find_one_document</span><span class="signature">(self, collection, json_query)</span>:
+ </div>
+
+ <details>
+ <summary>View Source</summary>
+ <div class="codehilite"><pre><span></span> <span class="k">def</span> <span class="nf">find_one_document</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">collection</span><span class="p">,</span> <span class="n">json_query</span><span class="p">):</span>
+ <span class="sd">"""</span>
+<span class="sd"> Finds the first document in the given collection that satisfies json_query.</span>
+
+<span class="sd"> Args:</span>
+<span class="sd"> collection: a string representing the collection name</span>
+<span class="sd"> json_query: a dict containing the query criteria (https://docs.mongodb.com/manual/tutorial/query-documents/)</span>
+
+<span class="sd"> Returns:</span>
+<span class="sd"> doc_json: a dictionary representing an iris, or None</span>
+<span class="sd"> """</span>
+ <span class="n">doc</span> <span class="o">=</span> <span class="n">collection</span><span class="o">.</span><span class="n">find_one</span><span class="p">(</span><span class="n">json_query</span><span class="p">)</span>
+ <span class="n">doc_json</span> <span class="o">=</span> <span class="n">Mongiris</span><span class="o">.</span><span class="n">bson_to_json</span><span class="p">(</span><span class="n">doc</span><span class="p">)</span>
+ <span class="k">return</span> <span class="n">doc_json</span>
+</pre></div>
+
+ </details>
+
+ <div class="docstring"><p>Finds the first document in the given collection that satisfies json_query.</p>
+
+<p>Args:
+ collection: a string representing the collection name
+ json_query: a dict containing the query criteria (https://docs.mongodb.com/manual/tutorial/query-documents/)</p>
+
+<p>Returns:
+ doc_json: a dictionary representing an iris, or None</p>
+</div>
+
+
+ </div>
+ <div id="Mongiris.find_all" class="classattr">
+ <div class="attr function"><a class="headerlink" href="#Mongiris.find_all">#  </a>
+
+
+ <span class="def">def</span>
+ <span class="name">find_all</span><span class="signature">(self, collection)</span>:
+ </div>
+
+ <details>
+ <summary>View Source</summary>
+ <div class="codehilite"><pre><span></span> <span class="k">def</span> <span class="nf">find_all</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">collection</span><span class="p">):</span>
+ <span class="sd">"""</span>
+<span class="sd"> Finds all documents in the given collection.</span>
+<span class="sd"> </span>
+<span class="sd"> Args:</span>
+<span class="sd"> collection: a string representing the collection name</span>
+<span class="sd"> </span>
+<span class="sd"> Returns:</span>
+<span class="sd"> doc_json: a dictionnary representing the documents, or None</span>
+<span class="sd"> """</span>
+ <span class="n">doc</span> <span class="o">=</span> <span class="n">collection</span><span class="o">.</span><span class="n">find</span><span class="p">()</span>
+ <span class="n">doc_json</span> <span class="o">=</span> <span class="n">Mongiris</span><span class="o">.</span><span class="n">bson_to_json</span><span class="p">(</span><span class="n">doc</span><span class="p">)</span>
+ <span class="k">return</span> <span class="n">doc_json</span>
+</pre></div>
+
+ </details>
+
+ <div class="docstring"><p>Finds all documents in the given collection.</p>
+
+<p>Args:
+ collection: a string representing the collection name</p>
+
+<p>Returns:
+ doc_json: a dictionnary representing the documents, or None</p>
+</div>
+
+
+ </div>
+ <div id="Mongiris.get_neighbourhood_from_code" class="classattr">
+ <div class="attr function"><a class="headerlink" href="#Mongiris.get_neighbourhood_from_code">#  </a>
+
+
+ <span class="def">def</span>
+ <span class="name">get_neighbourhood_from_code</span><span class="signature">(self, code_neighbourhood)</span>:
+ </div>
+
+ <details>
+ <summary>View Source</summary>
+ <div class="codehilite"><pre><span></span> <span class="k">def</span> <span class="nf">get_neighbourhood_from_code</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">code_neighbourhood</span><span class="p">):</span>
+ <span class="sd">"""</span>
+<span class="sd"> Returns the neighbourhood identified by the given code_neighbourhood.</span>
+
+<span class="sd"> Args:</span>
+<span class="sd"> code_neighbourhood: a string containing the code of the searched neighbourhood</span>
+
+<span class="sd"> Returns:</span>
+<span class="sd"> neighbourhood: a dictionary representing a neighbourhood, or None</span>
+<span class="sd"> """</span>
+ <span class="n">neighbourhood</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">find_one_document</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">collection_neighbourhoods</span><span class="p">,</span> <span class="p">{</span><span class="s2">"properties.CODE_IRIS"</span><span class="p">:</span> <span class="n">code_neighbourhood</span><span class="p">})</span>
+ <span class="k">return</span> <span class="n">neighbourhood</span>
+</pre></div>
+
+ </details>
+
+ <div class="docstring"><p>Returns the neighbourhood identified by the given code_neighbourhood.</p>
+
+<p>Args:
+ code_neighbourhood: a string containing the code of the searched neighbourhood</p>
+
+<p>Returns:
+ neighbourhood: a dictionary representing a neighbourhood, or None</p>
+</div>
+
+
+ </div>
+ <div id="Mongiris.find_documents" class="classattr">
+ <div class="attr function"><a class="headerlink" href="#Mongiris.find_documents">#  </a>
+
+
+ <span class="def">def</span>
+ <span class="name">find_documents</span><span class="signature">(self, collection, json_query, json_projection=None)</span>:
+ </div>
+
+ <details>
+ <summary>View Source</summary>
+ <div class="codehilite"><pre><span></span> <span class="k">def</span> <span class="nf">find_documents</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">collection</span><span class="p">,</span> <span class="n">json_query</span><span class="p">,</span> <span class="n">json_projection</span><span class="o">=</span><span class="kc">None</span><span class="p">):</span>
+ <span class="sd">"""</span>
+<span class="sd"> Finds the first document in the given collection that satisfies json_query.</span>
+
+<span class="sd"> Args:</span>
+<span class="sd"> collection: a string representing the collection name</span>
+<span class="sd"> json_query: a dict containing the query criteria (https://docs.mongodb.com/manual/tutorial/query-documents/)</span>
+<span class="sd"> json_projection: a json document indicating the fields that appear in the results</span>
+
+<span class="sd"> Returns:</span>
+<span class="sd"> doc_json: a cursor (set of documents)</span>
+<span class="sd"> """</span>
+ <span class="n">cursor</span> <span class="o">=</span> <span class="n">collection</span><span class="o">.</span><span class="n">find</span><span class="p">(</span><span class="n">json_query</span><span class="p">,</span> <span class="n">json_projection</span><span class="p">)</span>
+ <span class="n">doc_json</span> <span class="o">=</span> <span class="n">Mongiris</span><span class="o">.</span><span class="n">bson_to_json</span><span class="p">(</span><span class="n">cursor</span><span class="p">)</span>
+ <span class="k">return</span> <span class="n">doc_json</span>
+</pre></div>
+
+ </details>
+
+ <div class="docstring"><p>Finds the first document in the given collection that satisfies json_query.</p>
+
+<p>Args:
+ collection: a string representing the collection name
+ json_query: a dict containing the query criteria (https://docs.mongodb.com/manual/tutorial/query-documents/)
+ json_projection: a json document indicating the fields that appear in the results</p>
+
+<p>Returns:
+ doc_json: a cursor (set of documents)</p>
+</div>
+
+
+ </div>
+ <div id="Mongiris.get_random_document" class="classattr">
+ <div class="attr function"><a class="headerlink" href="#Mongiris.get_random_document">#  </a>
+
+
+ <span class="def">def</span>
+ <span class="name">get_random_document</span><span class="signature">(self, collection)</span>:
+ </div>
+
+ <details>
+ <summary>View Source</summary>
+ <div class="codehilite"><pre><span></span> <span class="k">def</span> <span class="nf">get_random_document</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">collection</span><span class="p">):</span>
+ <span class="sd">""" Returns a random document from the given collection. """</span>
+ <span class="n">random_iris</span> <span class="o">=</span> <span class="n">collection</span><span class="o">.</span><span class="n">aggregate</span><span class="p">([{</span><span class="s2">"$sample"</span><span class="p">:</span> <span class="p">{</span><span class="s2">"size"</span><span class="p">:</span> <span class="mi">1</span><span class="p">}}])</span><span class="o">.</span><span class="n">next</span><span class="p">()</span>
+ <span class="n">doc_json</span> <span class="o">=</span> <span class="n">Mongiris</span><span class="o">.</span><span class="n">bson_to_json</span><span class="p">(</span><span class="n">random_iris</span><span class="p">)</span>
+ <span class="k">return</span> <span class="n">doc_json</span>
+</pre></div>
+
+ </details>
+
+ <div class="docstring"><p>Returns a random document from the given collection.</p>
+</div>
+
+
+ </div>
+ <div id="Mongiris.update_one_document" class="classattr">
+ <div class="attr function"><a class="headerlink" href="#Mongiris.update_one_document">#  </a>
+
+
+ <span class="def">def</span>
+ <span class="name">update_one_document</span><span class="signature">(self, collection, json_query, json_updates)</span>:
+ </div>
+
+ <details>
+ <summary>View Source</summary>
+ <div class="codehilite"><pre><span></span> <span class="k">def</span> <span class="nf">update_one_document</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">collection</span><span class="p">,</span> <span class="n">json_query</span><span class="p">,</span> <span class="n">json_updates</span><span class="p">):</span>
+ <span class="sd">"""</span>
+<span class="sd"> Updates the first document satisfying json_query by setting new values from json_updates.</span>
+
+<span class="sd"> Args:</span>
+<span class="sd"> collection: a string representing the collection name</span>
+<span class="sd"> json_query: a dict containing the query criteria (https://docs.mongodb.com/manual/tutorial/query-documents/)</span>
+<span class="sd"> json_updates: a json document containing values to be updates (using $set operator)</span>
+
+<span class="sd"> Returns:</span>
+<span class="sd"> json_result: an UpdateResult json document containing information about the operation</span>
+<span class="sd"> """</span>
+ <span class="n">json_result</span> <span class="o">=</span> <span class="n">collection</span><span class="o">.</span><span class="n">update_one</span><span class="p">(</span><span class="n">json_query</span><span class="p">,</span> <span class="n">json_updates</span><span class="p">)</span>
+ <span class="k">return</span> <span class="n">json_result</span>
+</pre></div>
+
+ </details>
+
+ <div class="docstring"><p>Updates the first document satisfying json_query by setting new values from json_updates.</p>
+
+<p>Args:
+ collection: a string representing the collection name
+ json_query: a dict containing the query criteria (https://docs.mongodb.com/manual/tutorial/query-documents/)
+ json_updates: a json document containing values to be updates (using $set operator)</p>
+
+<p>Returns:
+ json_result: an UpdateResult json document containing information about the operation</p>
+</div>
+
+
+ </div>
+ <div id="Mongiris.replace_one_document" class="classattr">
+ <div class="attr function"><a class="headerlink" href="#Mongiris.replace_one_document">#  </a>
+
+
+ <span class="def">def</span>
+ <span class="name">replace_one_document</span><span class="signature">(self, collection, json_query, json_replace_doc, upsert=False)</span>:
+ </div>
+
+ <details>
+ <summary>View Source</summary>
+ <div class="codehilite"><pre><span></span> <span class="k">def</span> <span class="nf">replace_one_document</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">collection</span><span class="p">,</span> <span class="n">json_query</span><span class="p">,</span> <span class="n">json_replace_doc</span><span class="p">,</span> <span class="n">upsert</span><span class="o">=</span><span class="kc">False</span><span class="p">):</span>
+ <span class="sd">"""</span>
+<span class="sd"> Replaces the first document satisfying json_query by the document json_replace_doc (their _id are identical).</span>
+
+<span class="sd"> Args:</span>
+<span class="sd"> collection: a string representing the collection name</span>
+<span class="sd"> json_query: a dict containing the query criteria (https://docs.mongodb.com/manual/tutorial/query-documents/)</span>
+<span class="sd"> json_replace_doc: the replacement doc (if _id set, should be the same _id as the doc matching json_query)</span>
+<span class="sd"> upsert: a boolean, whether the json_replace_doc should be inserted if no document match json_query</span>
+
+<span class="sd"> Returns:</span>
+<span class="sd"> json_result: an UpdateResult json document containing information about the operation</span>
+<span class="sd"> """</span>
+ <span class="n">json_result</span> <span class="o">=</span> <span class="n">collection</span><span class="o">.</span><span class="n">replace_one</span><span class="p">(</span><span class="n">json_query</span><span class="p">,</span> <span class="n">json_replace_doc</span><span class="p">,</span> <span class="n">upsert</span><span class="p">)</span>
+ <span class="k">return</span> <span class="n">json_result</span>
+</pre></div>
+
+ </details>
+
+ <div class="docstring"><p>Replaces the first document satisfying json_query by the document json_replace_doc (their _id are identical).</p>
+
+<p>Args:
+ collection: a string representing the collection name
+ json_query: a dict containing the query criteria (https://docs.mongodb.com/manual/tutorial/query-documents/)
+ json_replace_doc: the replacement doc (if _id set, should be the same _id as the doc matching json_query)
+ upsert: a boolean, whether the json_replace_doc should be inserted if no document match json_query</p>
+
+<p>Returns:
+ json_result: an UpdateResult json document containing information about the operation</p>
+</div>
+
+
+ </div>
+ <div id="Mongiris.insert_one_document" class="classattr">
+ <div class="attr function"><a class="headerlink" href="#Mongiris.insert_one_document">#  </a>
+
+
+ <span class="def">def</span>
+ <span class="name">insert_one_document</span><span class="signature">(self, collection, doc)</span>:
+ </div>
+
+ <details>
+ <summary>View Source</summary>
+ <div class="codehilite"><pre><span></span> <span class="k">def</span> <span class="nf">insert_one_document</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">collection</span><span class="p">,</span> <span class="n">doc</span><span class="p">):</span>
+ <span class="sd">"""</span>
+<span class="sd"> Inserts a new document in the collection.</span>
+
+<span class="sd"> Args:</span>
+<span class="sd"> collection: a string representing the collection name</span>
+<span class="sd"> doc: a dict representing the document to be added</span>
+
+<span class="sd"> Returns:</span>
+<span class="sd"> json_result: an InsertOneResult json document containing information about the operation</span>
+<span class="sd"> """</span>
+ <span class="n">json_result</span> <span class="o">=</span> <span class="n">collection</span><span class="o">.</span><span class="n">insert_one</span><span class="p">(</span><span class="n">doc</span><span class="p">)</span>
+ <span class="k">return</span> <span class="n">json_result</span> <span class="c1"># eg, the new _id is in json_result.inserted_id</span>
+</pre></div>
+
+ </details>
+
+ <div class="docstring"><p>Inserts a new document in the collection.</p>
+
+<p>Args:
+ collection: a string representing the collection name
+ doc: a dict representing the document to be added</p>
+
+<p>Returns:
+ json_result: an InsertOneResult json document containing information about the operation</p>
+</div>
+
+
+ </div>
+ <div id="Mongiris.delete_all" class="classattr">
+ <div class="attr function"><a class="headerlink" href="#Mongiris.delete_all">#  </a>
+
+
+ <span class="def">def</span>
+ <span class="name">delete_all</span><span class="signature">(self, collection)</span>:
+ </div>
+
+ <details>
+ <summary>View Source</summary>
+ <div class="codehilite"><pre><span></span> <span class="k">def</span> <span class="nf">delete_all</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">collection</span><span class="p">):</span>
+ <span class="sd">"""</span>
+<span class="sd"> Deletes all documents in the collection.</span>
+
+<span class="sd"> Args:</span>
+<span class="sd"> collection: a string representing the collection name</span>
+
+<span class="sd"> Returns:</span>
+<span class="sd"> json_result: an DeleteResult json document containing information about the operation</span>
+<span class="sd"> """</span>
+ <span class="n">json_result</span> <span class="o">=</span> <span class="n">collection</span><span class="o">.</span><span class="n">delete_many</span><span class="p">({})</span> <span class="c1"># empty collection</span>
+ <span class="k">return</span> <span class="n">json_result</span>
+</pre></div>
+
+ </details>
+
+ <div class="docstring"><p>Deletes all documents in the collection.</p>
+
+<p>Args:
+ collection: a string representing the collection name</p>
+
+<p>Returns:
+ json_result: an DeleteResult json document containing information about the operation</p>
+</div>
+
+
+ </div>
+ <div id="Mongiris.geo_within" class="classattr">
+ <div class="attr function"><a class="headerlink" href="#Mongiris.geo_within">#  </a>
+
+
+ <span class="def">def</span>
+ <span class="name">geo_within</span><span class="signature">(self, collection, geometry, json_projection=None)</span>:
+ </div>
+
+ <details>
+ <summary>View Source</summary>
+ <div class="codehilite"><pre><span></span> <span class="k">def</span> <span class="nf">geo_within</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">collection</span><span class="p">,</span> <span class="n">geometry</span><span class="p">,</span> <span class="n">json_projection</span><span class="o">=</span><span class="kc">None</span><span class="p">):</span>
+ <span class="sd">"""</span>
+<span class="sd"> Finds all documents from given collection and which contain totally the given geometry.</span>
+<span class="sd"> Cannot be used to find the neighbourhood containing a point (geometry must be a polygon).</span>
+
+<span class="sd"> Args:</span>
+<span class="sd"> collection: a string representing the collection name</span>
+<span class="sd"> geometry: a geojson geometry ("Polygon", "$box" or "MultiPolygon", NO "Point")</span>
+<span class="sd"> json_projection: a json document indicating the fields that appear in the results</span>
+
+<span class="sd"> Returns:</span>
+<span class="sd"> doc_json: a cursor (set of documents)</span>
+<span class="sd"> """</span>
+ <span class="n">cursor</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">find_documents</span><span class="p">(</span><span class="n">collection</span><span class="p">,</span> <span class="p">{</span><span class="s2">"geometry"</span><span class="p">:</span> <span class="p">{</span><span class="s2">"$geoWithin"</span><span class="p">:</span> <span class="p">{</span><span class="s2">"$geometry"</span><span class="p">:</span> <span class="n">geometry</span><span class="p">}}},</span> <span class="n">json_projection</span><span class="p">)</span>
+ <span class="n">doc_json</span> <span class="o">=</span> <span class="n">Mongiris</span><span class="o">.</span><span class="n">bson_to_json</span><span class="p">(</span><span class="n">cursor</span><span class="p">)</span>
+ <span class="k">return</span> <span class="n">doc_json</span>
+</pre></div>
+
+ </details>
+
+ <div class="docstring"><p>Finds all documents from given collection and which contain totally the given geometry.
+Cannot be used to find the neighbourhood containing a point (geometry must be a polygon).</p>
+
+<p>Args:
+ collection: a string representing the collection name
+ geometry: a geojson geometry ("Polygon", "$box" or "MultiPolygon", NO "Point")
+ json_projection: a json document indicating the fields that appear in the results</p>
+
+<p>Returns:
+ doc_json: a cursor (set of documents)</p>
+</div>
+
+
+ </div>
+ <div id="Mongiris.geo_within_sphere" class="classattr">
+ <div class="attr function"><a class="headerlink" href="#Mongiris.geo_within_sphere">#  </a>
+
+
+ <span class="def">def</span>
+ <span class="name">geo_within_sphere</span><span class="signature">(self, collection, sphere, json_projection=None)</span>:
+ </div>
+
+ <details>
+ <summary>View Source</summary>
+ <div class="codehilite"><pre><span></span> <span class="k">def</span> <span class="nf">geo_within_sphere</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">collection</span><span class="p">,</span> <span class="n">sphere</span><span class="p">,</span> <span class="n">json_projection</span><span class="o">=</span><span class="kc">None</span><span class="p">):</span>
+ <span class="sd">"""</span>
+<span class="sd"> Finds all documents from given collection and which contain totally the given sphere.</span>
+<span class="sd"> Cannot be used to find the neighbourhood containing a point (geometry must be a polygon, with min. 3 points).</span>
+
+<span class="sd"> Args:</span>
+<span class="sd"> collection: a string representing the collection name</span>
+<span class="sd"> sphere: a geojson geometry defined by a center and a radius in radians</span>
+<span class="sd"> json_projection: a json document indicating the fields that appear in the results</span>
+
+<span class="sd"> Returns:</span>
+<span class="sd"> doc_json: a cursor (set of documents)</span>
+<span class="sd"> """</span>
+ <span class="n">cursor</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">find_documents</span><span class="p">(</span><span class="n">collection</span><span class="p">,</span> <span class="p">{</span><span class="s2">"geometry"</span><span class="p">:</span> <span class="p">{</span><span class="s2">"$geoWithin"</span><span class="p">:</span> <span class="n">sphere</span><span class="p">}},</span> <span class="n">json_projection</span><span class="p">)</span>
+ <span class="n">doc_json</span> <span class="o">=</span> <span class="n">Mongiris</span><span class="o">.</span><span class="n">bson_to_json</span><span class="p">(</span><span class="n">cursor</span><span class="p">)</span>
+ <span class="k">return</span> <span class="n">doc_json</span>
+</pre></div>
+
+ </details>
+
+ <div class="docstring"><p>Finds all documents from given collection and which contain totally the given sphere.
+Cannot be used to find the neighbourhood containing a point (geometry must be a polygon, with min. 3 points).</p>
+
+<p>Args:
+ collection: a string representing the collection name
+ sphere: a geojson geometry defined by a center and a radius in radians
+ json_projection: a json document indicating the fields that appear in the results</p>
+
+<p>Returns:
+ doc_json: a cursor (set of documents)</p>
+</div>
+
+
+ </div>
+ <div id="Mongiris.intersect" class="classattr">
+ <div class="attr function"><a class="headerlink" href="#Mongiris.intersect">#  </a>
+
+
+ <span class="def">def</span>
+ <span class="name">intersect</span><span class="signature">(self, collection, geometry, json_projection=None)</span>:
+ </div>
+
+ <details>
+ <summary>View Source</summary>
+ <div class="codehilite"><pre><span></span> <span class="k">def</span> <span class="nf">intersect</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">collection</span><span class="p">,</span> <span class="n">geometry</span><span class="p">,</span> <span class="n">json_projection</span><span class="o">=</span><span class="kc">None</span><span class="p">):</span>
+ <span class="sd">"""</span>
+<span class="sd"> Finds all documents from given collection and which intersect the given geometry.</span>
+
+<span class="sd"> Args:</span>
+<span class="sd"> collection: a string representing the collection name</span>
+<span class="sd"> geometry: a geojson geometry</span>
+<span class="sd"> json_projection: a json document indicating the fields that appear in the results</span>
+
+<span class="sd"> Returns:</span>
+<span class="sd"> doc_json: a cursor (set of documents)</span>
+<span class="sd"> """</span>
+ <span class="n">cursor</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">find_documents</span><span class="p">(</span><span class="n">collection</span><span class="p">,</span> <span class="p">{</span><span class="s2">"geometry"</span><span class="p">:</span> <span class="p">{</span><span class="s2">"$geoIntersects"</span><span class="p">:</span> <span class="p">{</span>
+ <span class="s2">"$geometry"</span><span class="p">:</span> <span class="n">geometry</span><span class="p">}}},</span> <span class="n">json_projection</span><span class="p">)</span>
+ <span class="n">doc_json</span> <span class="o">=</span> <span class="n">Mongiris</span><span class="o">.</span><span class="n">bson_to_json</span><span class="p">(</span><span class="n">cursor</span><span class="p">)</span>
+ <span class="k">return</span> <span class="n">doc_json</span>
+</pre></div>
+
+ </details>
+
+ <div class="docstring"><p>Finds all documents from given collection and which intersect the given geometry.</p>
+
+<p>Args:
+ collection: a string representing the collection name
+ geometry: a geojson geometry
+ json_projection: a json document indicating the fields that appear in the results</p>
+
+<p>Returns:
+ doc_json: a cursor (set of documents)</p>
+</div>
+
+
+ </div>
+ <div id="Mongiris.get_geojson_point" class="classattr">
+ <div class="attr function"><a class="headerlink" href="#Mongiris.get_geojson_point">#  </a>
+
+ <div class="decorator">@staticmethod</div>
+
+ <span class="def">def</span>
+ <span class="name">get_geojson_point</span><span class="signature">(coordinates)</span>:
+ </div>
+
+ <details>
+ <summary>View Source</summary>
+ <div class="codehilite"><pre><span></span> <span class="nd">@staticmethod</span>
+ <span class="k">def</span> <span class="nf">get_geojson_point</span><span class="p">(</span><span class="n">coordinates</span><span class="p">):</span>
+ <span class="sd">"""</span>
+<span class="sd"> Builds a dictionary with GeoJSON syntax for a point using the given coordinates.</span>
+
+<span class="sd"> Args:</span>
+<span class="sd"> coordinates: the coordinates (long, lat) as a list, e.g. [4.8, 45.7]</span>
+
+<span class="sd"> Returns:</span>
+<span class="sd"> point: a dictionary with GeoJSON syntax for a Point</span>
+<span class="sd"> """</span>
+ <span class="k">return</span> <span class="p">{</span><span class="s2">"type"</span><span class="p">:</span> <span class="s2">"Point"</span><span class="p">,</span> <span class="s2">"coordinates"</span><span class="p">:</span> <span class="n">coordinates</span><span class="p">}</span>
+</pre></div>
+
+ </details>
+
+ <div class="docstring"><p>Builds a dictionary with GeoJSON syntax for a point using the given coordinates.</p>
+
+<p>Args:
+ coordinates: the coordinates (long, lat) as a list, e.g. [4.8, 45.7]</p>
+
+<p>Returns:
+ point: a dictionary with GeoJSON syntax for a Point</p>
+</div>
+
+
+ </div>
+ <div id="Mongiris.convert_geojson_box_to_polygon" class="classattr">
+ <div class="attr function"><a class="headerlink" href="#Mongiris.convert_geojson_box_to_polygon">#  </a>
+
+ <div class="decorator">@staticmethod</div>
+
+ <span class="def">def</span>
+ <span class="name">convert_geojson_box_to_polygon</span><span class="signature">(lng1, lat1, lng2, lat2)</span>:
+ </div>
+
+ <details>
+ <summary>View Source</summary>
+ <div class="codehilite"><pre><span></span> <span class="nd">@staticmethod</span>
+ <span class="k">def</span> <span class="nf">convert_geojson_box_to_polygon</span><span class="p">(</span><span class="n">lng1</span><span class="p">,</span> <span class="n">lat1</span><span class="p">,</span> <span class="n">lng2</span><span class="p">,</span> <span class="n">lat2</span><span class="p">):</span>
+ <span class="sd">"""</span>
+<span class="sd"> Builds a dictionary with GeoJSON syntax for a polygon using two coordinates (points south-west and north-east).</span>
+<span class="sd"> This method builds the polygon by adding 2 missing points (north-west and south-east) and adds the starting</span>
+<span class="sd"> point (south-west) to end the loop.</span>
+<span class="sd"> The MongoDB $box operator is not supported with 2d-spherical indexes.</span>
+
+<span class="sd"> Args:</span>
+<span class="sd"> lng1: longitude of the first point (south-west) of the box</span>
+<span class="sd"> lat1: latitude of the first point (south-west) of the box</span>
+<span class="sd"> lng2: longitude of the second point (north-east) of the box</span>
+<span class="sd"> lat2: latitude of the second point (north-east) of the box</span>
+
+<span class="sd"> Returns:</span>
+<span class="sd"> box: a dictionary with GeoJSON syntax for a Box</span>
+<span class="sd"> """</span>
+ <span class="n">coordinates</span> <span class="o">=</span> <span class="p">[[[</span><span class="n">lng1</span><span class="p">,</span> <span class="n">lat1</span><span class="p">],</span> <span class="p">[</span><span class="n">lng1</span><span class="p">,</span> <span class="n">lat2</span><span class="p">],</span> <span class="p">[</span><span class="n">lng2</span><span class="p">,</span> <span class="n">lat2</span><span class="p">],</span> <span class="p">[</span><span class="n">lng2</span><span class="p">,</span> <span class="n">lat1</span><span class="p">],</span> <span class="p">[</span><span class="n">lng1</span><span class="p">,</span> <span class="n">lat1</span><span class="p">]]]</span>
+ <span class="k">return</span> <span class="n">Mongiris</span><span class="o">.</span><span class="n">get_geojson_polygon</span><span class="p">(</span><span class="n">coordinates</span><span class="p">)</span>
+</pre></div>
+
+ </details>
+
+ <div class="docstring"><p>Builds a dictionary with GeoJSON syntax for a polygon using two coordinates (points south-west and north-east).
This method builds the polygon by adding 2 missing points (north-west and south-east) and adds the starting
point (south-west) to end the loop.
The MongoDB $box operator is not supported with 2d-spherical indexes.</p>
-<h2 id="args">Args</h2>
-<dl>
-<dt><strong><code>lng1</code></strong></dt>
-<dd>longitude of the first point (south-west) of the box</dd>
-<dt><strong><code>lat1</code></strong></dt>
-<dd>latitude of the first point (south-west) of the box</dd>
-<dt><strong><code>lng2</code></strong></dt>
-<dd>longitude of the second point (north-east) of the box</dd>
-<dt><strong><code>lat2</code></strong></dt>
-<dd>latitude of the second point (north-east) of the box</dd>
-</dl>
-<h2 id="returns">Returns</h2>
-<dl>
-<dt><strong><code>box</code></strong></dt>
-<dd>a dictionary with GeoJSON syntax for a Box</dd>
-</dl></section>
-<details class="source">
-<summary>Source code</summary>
-<pre><code class="python">@staticmethod
-def convert_geojson_box_to_polygon(lng1, lat1, lng2, lat2):
- """
- Builds a dictionary with GeoJSON syntax for a polygon using two coordinates (points south-west and north-east).
- This method builds the polygon by adding 2 missing points (north-west and south-east) and adds the starting
- point (south-west) to end the loop.
- The MongoDB $box operator is not supported with 2d-spherical indexes.
-
- Args:
- lng1: longitude of the first point (south-west) of the box
- lat1: latitude of the first point (south-west) of the box
- lng2: longitude of the second point (north-east) of the box
- lat2: latitude of the second point (north-east) of the box
-
- Returns:
- box: a dictionary with GeoJSON syntax for a Box
- """
- coordinates = [[[lng1, lat1], [lng1, lat2], [lng2, lat2], [lng2, lat1], [lng1, lat1]]]
- return Mongiris.get_geojson_polygon(coordinates)</code></pre>
-</details>
-</dd>
-<dt id="api.Mongiris.get_geojson_point"><code class="name flex">
-<span>def <span class="ident">get_geojson_point</span></span>(<span>coordinates)</span>
-</code></dt>
-<dd>
-<section class="desc"><p>Builds a dictionary with GeoJSON syntax for a point using the given coordinates.</p>
-<h2 id="args">Args</h2>
-<dl>
-<dt><strong><code>coordinates</code></strong></dt>
-<dd>the coordinates (long, lat) as a list, e.g. [4.8, 45.7]</dd>
-</dl>
-<h2 id="returns">Returns</h2>
-<dl>
-<dt><strong><code>point</code></strong></dt>
-<dd>a dictionary with GeoJSON syntax for a Point</dd>
-</dl></section>
-<details class="source">
-<summary>Source code</summary>
-<pre><code class="python">@staticmethod
-def get_geojson_point(coordinates):
- """
- Builds a dictionary with GeoJSON syntax for a point using the given coordinates.
-
- Args:
- coordinates: the coordinates (long, lat) as a list, e.g. [4.8, 45.7]
-
- Returns:
- point: a dictionary with GeoJSON syntax for a Point
- """
- return {"type": "Point", "coordinates": coordinates}</code></pre>
-</details>
-</dd>
-<dt id="api.Mongiris.get_geojson_polygon"><code class="name flex">
-<span>def <span class="ident">get_geojson_polygon</span></span>(<span>coordinates)</span>
-</code></dt>
-<dd>
-<section class="desc"><p>Builds a dictionary with GeoJSON syntax for a polygon using the given coordinates.
+
+<p>Args:
+ lng1: longitude of the first point (south-west) of the box
+ lat1: latitude of the first point (south-west) of the box
+ lng2: longitude of the second point (north-east) of the box
+ lat2: latitude of the second point (north-east) of the box</p>
+
+<p>Returns:
+ box: a dictionary with GeoJSON syntax for a Box</p>
+</div>
+
+
+ </div>
+ <div id="Mongiris.get_geojson_polygon" class="classattr">
+ <div class="attr function"><a class="headerlink" href="#Mongiris.get_geojson_polygon">#  </a>
+
+ <div class="decorator">@staticmethod</div>
+
+ <span class="def">def</span>
+ <span class="name">get_geojson_polygon</span><span class="signature">(coordinates)</span>:
+ </div>
+
+ <details>
+ <summary>View Source</summary>
+ <div class="codehilite"><pre><span></span> <span class="nd">@staticmethod</span>
+ <span class="k">def</span> <span class="nf">get_geojson_polygon</span><span class="p">(</span><span class="n">coordinates</span><span class="p">):</span>
+ <span class="sd">"""</span>
+<span class="sd"> Builds a dictionary with GeoJSON syntax for a polygon using the given coordinates.</span>
+<span class="sd"> Careful: polygons must be closed ! (first coordinate must be identical to last coordinate)</span>
+
+<span class="sd"> Args:</span>
+<span class="sd"> coordinates: the coordinates (long, lat) as a list of list, e.g. [[[4.8, 45.7], [4.9, 47.8]]]</span>
+
+<span class="sd"> Returns:</span>
+<span class="sd"> polygon: a dictionary with GeoJSON syntax for a Polygon</span>
+<span class="sd"> """</span>
+ <span class="k">return</span> <span class="p">{</span><span class="s2">"type"</span><span class="p">:</span> <span class="s2">"Polygon"</span><span class="p">,</span> <span class="s2">"coordinates"</span><span class="p">:</span> <span class="n">coordinates</span><span class="p">}</span>
+</pre></div>
+
+ </details>
+
+ <div class="docstring"><p>Builds a dictionary with GeoJSON syntax for a polygon using the given coordinates.
Careful: polygons must be closed ! (first coordinate must be identical to last coordinate)</p>
-<h2 id="args">Args</h2>
-<dl>
-<dt><strong><code>coordinates</code></strong></dt>
-<dd>the coordinates (long, lat) as a list of list, e.g. [[[4.8, 45.7], [4.9, 47.8]]]</dd>
-</dl>
-<h2 id="returns">Returns</h2>
-<dl>
-<dt><strong><code>polygon</code></strong></dt>
-<dd>a dictionary with GeoJSON syntax for a Polygon</dd>
-</dl></section>
-<details class="source">
-<summary>Source code</summary>
-<pre><code class="python">@staticmethod
-def get_geojson_polygon(coordinates):
- """
- Builds a dictionary with GeoJSON syntax for a polygon using the given coordinates.
- Careful: polygons must be closed ! (first coordinate must be identical to last coordinate)
-
- Args:
- coordinates: the coordinates (long, lat) as a list of list, e.g. [[[4.8, 45.7], [4.9, 47.8]]]
-
- Returns:
- polygon: a dictionary with GeoJSON syntax for a Polygon
- """
- return {"type": "Polygon", "coordinates": coordinates}</code></pre>
-</details>
-</dd>
-</dl>
-<h3>Methods</h3>
-<dl>
-<dt id="api.Mongiris.count_documents"><code class="name flex">
-<span>def <span class="ident">count_documents</span></span>(<span>self, collection, json_query)</span>
-</code></dt>
-<dd>
-<section class="desc"><p>Counts the number of documents that satisfy json_query in the given collection.</p>
-<h2 id="args">Args</h2>
-<dl>
-<dt><strong><code>collection</code></strong></dt>
-<dd>a string representing the collection name</dd>
-<dt><strong><code>json_query</code></strong></dt>
-<dd>a dict containing the query criteria (<a href="https://docs.mongodb.com/manual/tutorial/query-documents/">https://docs.mongodb.com/manual/tutorial/query-documents/</a>)</dd>
-</dl>
-<h2 id="returns">Returns</h2>
-<dl>
-<dt><strong><code>count</code></strong></dt>
-<dd>an integer representing the number of documents</dd>
-</dl></section>
-<details class="source">
-<summary>Source code</summary>
-<pre><code class="python">def count_documents(self, collection, json_query):
- """
- Counts the number of documents that satisfy json_query in the given collection.
-
- Args:
- collection: a string representing the collection name
- json_query: a dict containing the query criteria (https://docs.mongodb.com/manual/tutorial/query-documents/)
-
- Returns:
- count: an integer representing the number of documents
- """
- return collection.count_documents(json_query)</code></pre>
-</details>
-</dd>
-<dt id="api.Mongiris.create_index"><code class="name flex">
-<span>def <span class="ident">create_index</span></span>(<span>self, iris_collection)</span>
-</code></dt>
-<dd>
-<section class="desc"><p>Rebuilds a geospatial index on the iris collection. Only used in case of restoration/import.</p></section>
-<details class="source">
-<summary>Source code</summary>
-<pre><code class="python">def create_index(self, iris_collection):
- """ Rebuilds a geospatial index on the iris collection. Only used in case of restoration/import. """
- self.logger.info("Creating index on 'geometry' using " + pymongo.GEOSPHERE)
- iris_collection.create_index([("geometry", pymongo.GEOSPHERE)])
- self.logger.info("Index created")</code></pre>
-</details>
-</dd>
-<dt id="api.Mongiris.delete_all"><code class="name flex">
-<span>def <span class="ident">delete_all</span></span>(<span>self, collection)</span>
-</code></dt>
-<dd>
-<section class="desc"><p>Deletes all documents in the collection.</p>
-<h2 id="args">Args</h2>
-<dl>
-<dt><strong><code>collection</code></strong></dt>
-<dd>a string representing the collection name</dd>
-</dl>
-<h2 id="returns">Returns</h2>
-<dl>
-<dt><strong><code>json_result</code></strong></dt>
-<dd>an DeleteResult json document containing information about the operation</dd>
-</dl></section>
-<details class="source">
-<summary>Source code</summary>
-<pre><code class="python">def delete_all(self, collection):
- """
- Deletes all documents in the collection.
-
- Args:
- collection: a string representing the collection name
-
- Returns:
- json_result: an DeleteResult json document containing information about the operation
- """
- json_result = collection.delete_many({}) # empty collection
- return json_result</code></pre>
-</details>
-</dd>
-<dt id="api.Mongiris.find_documents"><code class="name flex">
-<span>def <span class="ident">find_documents</span></span>(<span>self, collection, json_query, json_projection=None)</span>
-</code></dt>
-<dd>
-<section class="desc"><p>Finds the first document in the given collection that satisfies json_query.</p>
-<h2 id="args">Args</h2>
-<dl>
-<dt><strong><code>collection</code></strong></dt>
-<dd>a string representing the collection name</dd>
-<dt><strong><code>json_query</code></strong></dt>
-<dd>a dict containing the query criteria (<a href="https://docs.mongodb.com/manual/tutorial/query-documents/">https://docs.mongodb.com/manual/tutorial/query-documents/</a>)</dd>
-<dt><strong><code>json_projection</code></strong></dt>
-<dd>a json document indicating the fields that appear in the results</dd>
-</dl>
-<h2 id="returns">Returns</h2>
-<dl>
-<dt><strong><code>doc_json</code></strong></dt>
-<dd>a cursor (set of documents)</dd>
-</dl></section>
-<details class="source">
-<summary>Source code</summary>
-<pre><code class="python">def find_documents(self, collection, json_query, json_projection=None):
- """
- Finds the first document in the given collection that satisfies json_query.
-
- Args:
- collection: a string representing the collection name
- json_query: a dict containing the query criteria (https://docs.mongodb.com/manual/tutorial/query-documents/)
- json_projection: a json document indicating the fields that appear in the results
-
- Returns:
- doc_json: a cursor (set of documents)
- """
- cursor = collection.find(json_query, json_projection)
- doc_json = Mongiris.bson_to_json(cursor)
- return doc_json</code></pre>
-</details>
-</dd>
-<dt id="api.Mongiris.find_one_document"><code class="name flex">
-<span>def <span class="ident">find_one_document</span></span>(<span>self, collection, json_query)</span>
-</code></dt>
-<dd>
-<section class="desc"><p>Finds the first document in the given collection that satisfies json_query.</p>
-<h2 id="args">Args</h2>
-<dl>
-<dt><strong><code>collection</code></strong></dt>
-<dd>a string representing the collection name</dd>
-<dt><strong><code>json_query</code></strong></dt>
-<dd>a dict containing the query criteria (<a href="https://docs.mongodb.com/manual/tutorial/query-documents/">https://docs.mongodb.com/manual/tutorial/query-documents/</a>)</dd>
-</dl>
-<h2 id="returns">Returns</h2>
-<dl>
-<dt><strong><code>doc_json</code></strong></dt>
-<dd>a dictionary representing an iris, or None</dd>
-</dl></section>
-<details class="source">
-<summary>Source code</summary>
-<pre><code class="python">def find_one_document(self, collection, json_query):
- """
- Finds the first document in the given collection that satisfies json_query.
-
- Args:
- collection: a string representing the collection name
- json_query: a dict containing the query criteria (https://docs.mongodb.com/manual/tutorial/query-documents/)
-
- Returns:
- doc_json: a dictionary representing an iris, or None
- """
- doc = collection.find_one(json_query)
- doc_json = Mongiris.bson_to_json(doc)
- return doc_json</code></pre>
-</details>
-</dd>
-<dt id="api.Mongiris.geo_within"><code class="name flex">
-<span>def <span class="ident">geo_within</span></span>(<span>self, collection, geometry, json_projection=None)</span>
-</code></dt>
-<dd>
-<section class="desc"><p>Finds all documents from given collection and which contain totally the given geometry.
-Cannot be used to find the IRIS containing a point (geometry must be a polygon).</p>
-<h2 id="args">Args</h2>
-<dl>
-<dt><strong><code>collection</code></strong></dt>
-<dd>a string representing the collection name</dd>
-<dt><strong><code>geometry</code></strong></dt>
-<dd>a geojson geometry ("Polygon", "$box" or "MultiPolygon", NO "Point")</dd>
-<dt><strong><code>json_projection</code></strong></dt>
-<dd>a json document indicating the fields that appear in the results</dd>
-</dl>
-<h2 id="returns">Returns</h2>
-<dl>
-<dt><strong><code>doc_json</code></strong></dt>
-<dd>a cursor (set of documents)</dd>
-</dl></section>
-<details class="source">
-<summary>Source code</summary>
-<pre><code class="python">def geo_within(self, collection, geometry, json_projection=None):
- """
- Finds all documents from given collection and which contain totally the given geometry.
- Cannot be used to find the IRIS containing a point (geometry must be a polygon).
-
- Args:
- collection: a string representing the collection name
- geometry: a geojson geometry ("Polygon", "$box" or "MultiPolygon", NO "Point")
- json_projection: a json document indicating the fields that appear in the results
-
- Returns:
- doc_json: a cursor (set of documents)
- """
- cursor = self.find_documents(collection, {"geometry": {"$geoWithin": {"$geometry": geometry}}}, json_projection)
- doc_json = Mongiris.bson_to_json(cursor)
- return doc_json</code></pre>
-</details>
-</dd>
-<dt id="api.Mongiris.geo_within_sphere"><code class="name flex">
-<span>def <span class="ident">geo_within_sphere</span></span>(<span>self, collection, sphere, json_projection=None)</span>
-</code></dt>
-<dd>
-<section class="desc"><p>Finds all documents from given collection and which contain totally the given sphere.
-Cannot be used to find the IRIS containing a point (geometry must be a polygon, with min. 3 points).</p>
-<h2 id="args">Args</h2>
-<dl>
-<dt><strong><code>collection</code></strong></dt>
-<dd>a string representing the collection name</dd>
-<dt><strong><code>sphere</code></strong></dt>
-<dd>a geojson geometry defined by a center and a radius in radians</dd>
-<dt><strong><code>json_projection</code></strong></dt>
-<dd>a json document indicating the fields that appear in the results</dd>
-</dl>
-<h2 id="returns">Returns</h2>
-<dl>
-<dt><strong><code>doc_json</code></strong></dt>
-<dd>a cursor (set of documents)</dd>
-</dl></section>
-<details class="source">
-<summary>Source code</summary>
-<pre><code class="python">def geo_within_sphere(self, collection, sphere, json_projection=None):
- """
- Finds all documents from given collection and which contain totally the given sphere.
- Cannot be used to find the IRIS containing a point (geometry must be a polygon, with min. 3 points).
-
- Args:
- collection: a string representing the collection name
- sphere: a geojson geometry defined by a center and a radius in radians
- json_projection: a json document indicating the fields that appear in the results
-
- Returns:
- doc_json: a cursor (set of documents)
- """
- cursor = self.find_documents(collection, {"geometry": {"$geoWithin": sphere}}, json_projection)
- doc_json = Mongiris.bson_to_json(cursor)
- return doc_json</code></pre>
-</details>
-</dd>
-<dt id="api.Mongiris.get_iris_from_code"><code class="name flex">
-<span>def <span class="ident">get_iris_from_code</span></span>(<span>self, code_iris)</span>
-</code></dt>
-<dd>
-<section class="desc"><p>Returns the iris identified by the given code_iris.</p>
-<h2 id="args">Args</h2>
-<dl>
-<dt><strong><code>code_iris</code></strong></dt>
-<dd>a string containing the code of the searched iris</dd>
-</dl>
-<h2 id="returns">Returns</h2>
-<dl>
-<dt><strong><code>iris</code></strong></dt>
-<dd>a dictionary representing an iris, or None</dd>
-</dl></section>
-<details class="source">
-<summary>Source code</summary>
-<pre><code class="python">def get_iris_from_code(self, code_iris):
- """
- Returns the iris identified by the given code_iris.
-
- Args:
- code_iris: a string containing the code of the searched iris
-
- Returns:
- iris: a dictionary representing an iris, or None
- """
- iris = self.find_one_document(self.collection_iris, {"properties.CODE_IRIS": code_iris})
- return iris</code></pre>
-</details>
-</dd>
-<dt id="api.Mongiris.get_random_document"><code class="name flex">
-<span>def <span class="ident">get_random_document</span></span>(<span>self, collection)</span>
-</code></dt>
-<dd>
-<section class="desc"><p>Returns a random document from the given collection.</p></section>
-<details class="source">
-<summary>Source code</summary>
-<pre><code class="python">def get_random_document(self, collection):
- """ Returns a random document from the given collection. """
- random_iris = collection.aggregate([{"$sample": {"size": 1}}]).next()
- doc_json = Mongiris.bson_to_json(random_iris)
- return doc_json</code></pre>
-</details>
-</dd>
-<dt id="api.Mongiris.init_connection"><code class="name flex">
-<span>def <span class="ident">init_connection</span></span>(<span>self)</span>
-</code></dt>
-<dd>
-<section class="desc"><p>Tries to connect to MongoDB. The output connection object do not provide reliable connection status, only the
-boolean connection_status indicates whether the connection is working or not.</p>
-<h2 id="returns">Returns</h2>
-<dl>
-<dt><strong><code>connection</code></strong></dt>
-<dd>an object with information about the connection</dd>
-<dt><strong><code>connection_status</code></strong></dt>
-<dd>a boolean indicating whether the connection is a success or a failure</dd>
-</dl></section>
-<details class="source">
-<summary>Source code</summary>
-<pre><code class="python">def init_connection(self):
- """
- Tries to connect to MongoDB. The output connection object do not provide reliable connection status, only the
- boolean connection_status indicates whether the connection is working or not.
-
- Returns:
- connection: an object with information about the connection
- connection_status: a boolean indicating whether the connection is a success or a failure
- """
- connection_status = True # by default, connection is ok
- connection = None
- try:
- connection = pymongo.MongoClient(serverSelectionTimeoutMS=config.max_timeout) # default localhost:27017
- connection.server_info() # forces a query to MongoDB (for checking the connection)
- except pymongo.errors.ServerSelectionTimeoutError as e:
- self.logger.error('Could not connect to the MongoDB database ! Have you launched MongoDB ? ' + str(e))
- connection_status = False
- return connection, connection_status</code></pre>
-</details>
-</dd>
-<dt id="api.Mongiris.insert_one_document"><code class="name flex">
-<span>def <span class="ident">insert_one_document</span></span>(<span>self, collection, doc)</span>
-</code></dt>
-<dd>
-<section class="desc"><p>Inserts a new document in the collection.</p>
-<h2 id="args">Args</h2>
-<dl>
-<dt><strong><code>collection</code></strong></dt>
-<dd>a string representing the collection name</dd>
-<dt><strong><code>doc</code></strong></dt>
-<dd>a dict representing the document to be added</dd>
-</dl>
-<h2 id="returns">Returns</h2>
-<dl>
-<dt><strong><code>json_result</code></strong></dt>
-<dd>an InsertOneResult json document containing information about the operation</dd>
-</dl></section>
-<details class="source">
-<summary>Source code</summary>
-<pre><code class="python">def insert_one_document(self, collection, doc):
- """
- Inserts a new document in the collection.
-
- Args:
- collection: a string representing the collection name
- doc: a dict representing the document to be added
-
- Returns:
- json_result: an InsertOneResult json document containing information about the operation
- """
- json_result = collection.insert_one(doc)
- return json_result # eg, the new _id is in json_result.inserted_id</code></pre>
-</details>
-</dd>
-<dt id="api.Mongiris.intersect"><code class="name flex">
-<span>def <span class="ident">intersect</span></span>(<span>self, collection, geometry, json_projection=None)</span>
-</code></dt>
-<dd>
-<section class="desc"><p>Finds all documents from given collection and which intersect the given geometry.</p>
-<h2 id="args">Args</h2>
-<dl>
-<dt><strong><code>collection</code></strong></dt>
-<dd>a string representing the collection name</dd>
-<dt><strong><code>geometry</code></strong></dt>
-<dd>a geojson geometry</dd>
-<dt><strong><code>json_projection</code></strong></dt>
-<dd>a json document indicating the fields that appear in the results</dd>
-</dl>
-<h2 id="returns">Returns</h2>
-<dl>
-<dt><strong><code>doc_json</code></strong></dt>
-<dd>a cursor (set of documents)</dd>
-</dl></section>
-<details class="source">
-<summary>Source code</summary>
-<pre><code class="python">def intersect(self, collection, geometry, json_projection=None):
- """
- Finds all documents from given collection and which intersect the given geometry.
-
- Args:
- collection: a string representing the collection name
- geometry: a geojson geometry
- json_projection: a json document indicating the fields that appear in the results
-
- Returns:
- doc_json: a cursor (set of documents)
- """
- cursor = self.find_documents(collection, {"geometry": {"$geoIntersects": {
- "$geometry": geometry}}}, json_projection)
- doc_json = Mongiris.bson_to_json(cursor)
- return doc_json</code></pre>
-</details>
-</dd>
-<dt id="api.Mongiris.near"><code class="name flex">
-<span>def <span class="ident">near</span></span>(<span>self, collection, coordinates, json_projection=None, distance_max=2000)</span>
-</code></dt>
-<dd>
-<section class="desc"><p>Finds all documents from given collection and which are near the given geometry (according to distance_max).</p>
-<h2 id="args">Args</h2>
-<dl>
-<dt><strong><code>collection</code></strong></dt>
-<dd>a string representing the collection name</dd>
-<dt><strong><code>coordinates</code></strong></dt>
-<dd>an array of coordinates (long, lat) - near only accepts Point</dd>
-<dt><strong><code>json_projection</code></strong></dt>
-<dd>a json document indicating the fields that appear in the results</dd>
-<dt><strong><code>distance_max</code></strong></dt>
-<dd>the maximum distance of resulting iris, in meters</dd>
-</dl>
-<h2 id="returns">Returns</h2>
-<dl>
-<dt><strong><code>doc_json</code></strong></dt>
-<dd>a cursor (set of documents)</dd>
-</dl></section>
-<details class="source">
-<summary>Source code</summary>
-<pre><code class="python">def near(self, collection, coordinates, json_projection=None, distance_max=2000):
- """
- Finds all documents from given collection and which are near the given geometry (according to distance_max).
-
- Args:
- collection: a string representing the collection name
- coordinates: an array of coordinates (long, lat) - near only accepts Point
- json_projection: a json document indicating the fields that appear in the results
- distance_max: the maximum distance of resulting iris, in meters
-
- Returns:
- doc_json: a cursor (set of documents)
- """
- geometry = Mongiris.get_geojson_point(coordinates)
- cursor = self.find_documents(collection, {"geometry": {"$near": {
- "$geometry": geometry, "$maxDistance": distance_max}}}, json_projection)
- doc_json = Mongiris.bson_to_json(cursor)
- return doc_json</code></pre>
-</details>
-</dd>
-<dt id="api.Mongiris.point_in_which_iris"><code class="name flex">
-<span>def <span class="ident">point_in_which_iris</span></span>(<span>self, coordinates, json_projection=None)</span>
-</code></dt>
-<dd>
-<section class="desc"><p>Finds the document (IRIS) containing the given coordinates. Uses near() since geo_within() requires a Polygon.
-Careful: the near() operator may return several iris (low probability since distance = 1 meter) and only the
-first one is returned.</p>
-<h2 id="args">Args</h2>
-<dl>
-<dt><strong><code>coordinates</code></strong></dt>
-<dd>an array of coordinates (long, lat)</dd>
-<dt><strong><code>json_projection</code></strong></dt>
-<dd>a json document indicating the fields that appear in the results</dd>
-</dl>
-<h2 id="returns">Returns</h2>
-<dl>
-<dt><strong><code>doc_json</code></strong></dt>
-<dd>a json document or None</dd>
-</dl></section>
-<details class="source">
-<summary>Source code</summary>
-<pre><code class="python">def point_in_which_iris(self, coordinates, json_projection=None):
- """
- Finds the document (IRIS) containing the given coordinates. Uses near() since geo_within() requires a Polygon.
- Careful: the near() operator may return several iris (low probability since distance = 1 meter) and only the
- first one is returned.
-
- Args:
- coordinates: an array of coordinates (long, lat)
- json_projection: a json document indicating the fields that appear in the results
-
- Returns:
- doc_json: a json document or None
- """
- results = self.near(self.collection_iris, coordinates, json_projection, 1) # distance = 1 meter
- if len(results) == 0:
- return None
- return results[0]</code></pre>
-</details>
-</dd>
-<dt id="api.Mongiris.replace_one_document"><code class="name flex">
-<span>def <span class="ident">replace_one_document</span></span>(<span>self, collection, json_query, json_replace_doc, upsert=False)</span>
-</code></dt>
-<dd>
-<section class="desc"><p>Replaces the first document satisfying json_query by the document json_replace_doc (their _id are identical).</p>
-<h2 id="args">Args</h2>
-<dl>
-<dt><strong><code>collection</code></strong></dt>
-<dd>a string representing the collection name</dd>
-<dt><strong><code>json_query</code></strong></dt>
-<dd>a dict containing the query criteria (<a href="https://docs.mongodb.com/manual/tutorial/query-documents/">https://docs.mongodb.com/manual/tutorial/query-documents/</a>)</dd>
-<dt><strong><code>json_replace_doc</code></strong></dt>
-<dd>the replacement doc (if _id set, should be the same _id as the doc matching json_query)</dd>
-<dt><strong><code>upsert</code></strong></dt>
-<dd>a boolean, whether the json_replace_doc should be inserted if no document match json_query</dd>
-</dl>
-<h2 id="returns">Returns</h2>
-<dl>
-<dt><strong><code>json_result</code></strong></dt>
-<dd>an UpdateResult json document containing information about the operation</dd>
-</dl></section>
-<details class="source">
-<summary>Source code</summary>
-<pre><code class="python">def replace_one_document(self, collection, json_query, json_replace_doc, upsert=False):
- """
- Replaces the first document satisfying json_query by the document json_replace_doc (their _id are identical).
-
- Args:
- collection: a string representing the collection name
- json_query: a dict containing the query criteria (https://docs.mongodb.com/manual/tutorial/query-documents/)
- json_replace_doc: the replacement doc (if _id set, should be the same _id as the doc matching json_query)
- upsert: a boolean, whether the json_replace_doc should be inserted if no document match json_query
-
- Returns:
- json_result: an UpdateResult json document containing information about the operation
- """
- json_result = collection.replace_one(json_query, json_replace_doc, upsert)
- return json_result</code></pre>
-</details>
-</dd>
-<dt id="api.Mongiris.update_one_document"><code class="name flex">
-<span>def <span class="ident">update_one_document</span></span>(<span>self, collection, json_query, json_updates)</span>
-</code></dt>
-<dd>
-<section class="desc"><p>Updates the first document satisfying json_query by setting new values from json_updates.</p>
-<h2 id="args">Args</h2>
-<dl>
-<dt><strong><code>collection</code></strong></dt>
-<dd>a string representing the collection name</dd>
-<dt><strong><code>json_query</code></strong></dt>
-<dd>a dict containing the query criteria (<a href="https://docs.mongodb.com/manual/tutorial/query-documents/">https://docs.mongodb.com/manual/tutorial/query-documents/</a>)</dd>
-<dt><strong><code>json_updates</code></strong></dt>
-<dd>a json document containing values to be updates (using $set operator)</dd>
-</dl>
-<h2 id="returns">Returns</h2>
-<dl>
-<dt><strong><code>json_result</code></strong></dt>
-<dd>an UpdateResult json document containing information about the operation</dd>
-</dl></section>
-<details class="source">
-<summary>Source code</summary>
-<pre><code class="python">def update_one_document(self, collection, json_query, json_updates):
- """
- Updates the first document satisfying json_query by setting new values from json_updates.
-
- Args:
- collection: a string representing the collection name
- json_query: a dict containing the query criteria (https://docs.mongodb.com/manual/tutorial/query-documents/)
- json_updates: a json document containing values to be updates (using $set operator)
-
- Returns:
- json_result: an UpdateResult json document containing information about the operation
- """
- json_result = collection.update_one(json_query, json_updates)
- return json_result</code></pre>
-</details>
-</dd>
-</dl>
-</dd>
-</dl>
-</section>
-</article>
-<nav id="sidebar">
-<h1>Index</h1>
-<div class="toc">
-<ul></ul>
+
+<p>Args:
+ coordinates: the coordinates (long, lat) as a list of list, e.g. [[[4.8, 45.7], [4.9, 47.8]]]</p>
+
+<p>Returns:
+ polygon: a dictionary with GeoJSON syntax for a Polygon</p>
</div>
-<ul id="index">
-<li><h3><a href="#header-classes">Classes</a></h3>
-<ul>
-<li>
-<h4><code><a title="api.Mongiris" href="#api.Mongiris">Mongiris</a></code></h4>
-<ul class="">
-<li><code><a title="api.Mongiris.adjacent" href="#api.Mongiris.adjacent">adjacent</a></code></li>
-<li><code><a title="api.Mongiris.bson_to_json" href="#api.Mongiris.bson_to_json">bson_to_json</a></code></li>
-<li><code><a title="api.Mongiris.convert_geojson_box_to_polygon" href="#api.Mongiris.convert_geojson_box_to_polygon">convert_geojson_box_to_polygon</a></code></li>
-<li><code><a title="api.Mongiris.count_documents" href="#api.Mongiris.count_documents">count_documents</a></code></li>
-<li><code><a title="api.Mongiris.create_index" href="#api.Mongiris.create_index">create_index</a></code></li>
-<li><code><a title="api.Mongiris.delete_all" href="#api.Mongiris.delete_all">delete_all</a></code></li>
-<li><code><a title="api.Mongiris.find_documents" href="#api.Mongiris.find_documents">find_documents</a></code></li>
-<li><code><a title="api.Mongiris.find_one_document" href="#api.Mongiris.find_one_document">find_one_document</a></code></li>
-<li><code><a title="api.Mongiris.geo_within" href="#api.Mongiris.geo_within">geo_within</a></code></li>
-<li><code><a title="api.Mongiris.geo_within_sphere" href="#api.Mongiris.geo_within_sphere">geo_within_sphere</a></code></li>
-<li><code><a title="api.Mongiris.get_geojson_point" href="#api.Mongiris.get_geojson_point">get_geojson_point</a></code></li>
-<li><code><a title="api.Mongiris.get_geojson_polygon" href="#api.Mongiris.get_geojson_polygon">get_geojson_polygon</a></code></li>
-<li><code><a title="api.Mongiris.get_iris_from_code" href="#api.Mongiris.get_iris_from_code">get_iris_from_code</a></code></li>
-<li><code><a title="api.Mongiris.get_random_document" href="#api.Mongiris.get_random_document">get_random_document</a></code></li>
-<li><code><a title="api.Mongiris.init_connection" href="#api.Mongiris.init_connection">init_connection</a></code></li>
-<li><code><a title="api.Mongiris.insert_one_document" href="#api.Mongiris.insert_one_document">insert_one_document</a></code></li>
-<li><code><a title="api.Mongiris.intersect" href="#api.Mongiris.intersect">intersect</a></code></li>
-<li><code><a title="api.Mongiris.near" href="#api.Mongiris.near">near</a></code></li>
-<li><code><a title="api.Mongiris.point_in_which_iris" href="#api.Mongiris.point_in_which_iris">point_in_which_iris</a></code></li>
-<li><code><a title="api.Mongiris.replace_one_document" href="#api.Mongiris.replace_one_document">replace_one_document</a></code></li>
-<li><code><a title="api.Mongiris.update_one_document" href="#api.Mongiris.update_one_document">update_one_document</a></code></li>
-</ul>
-</li>
-</ul>
-</li>
-</ul>
-</nav>
-</main>
-<footer id="footer">
-<p>Generated by <a href="https://pdoc3.github.io/pdoc"><cite>pdoc</cite> 0.6.3</a>.</p>
-</footer>
-<script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/9.12.0/highlight.min.js"></script>
-<script>hljs.initHighlightingOnLoad()</script>
+
+
+ </div>
+ <div id="Mongiris.point_in_which_neighbourhood" class="classattr">
+ <div class="attr function"><a class="headerlink" href="#Mongiris.point_in_which_neighbourhood">#  </a>
+
+
+ <span class="def">def</span>
+ <span class="name">point_in_which_neighbourhood</span><span class="signature">(self, coordinates, json_projection=None)</span>:
+ </div>
+
+ <details>
+ <summary>View Source</summary>
+ <div class="codehilite"><pre><span></span> <span class="k">def</span> <span class="nf">point_in_which_neighbourhood</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">coordinates</span><span class="p">,</span> <span class="n">json_projection</span><span class="o">=</span><span class="kc">None</span><span class="p">):</span>
+ <span class="sd">"""</span>
+<span class="sd"> Finds the document (neighbourhood) containing the given coordinates. Uses near() since geo_within() requires a</span>
+<span class="sd"> Polygon.</span>
+<span class="sd"> Careful: the near() operator may return several neighbourhoods (low probability since distance = 1 meter) and</span>
+<span class="sd"> only the first one is returned.</span>
+
+<span class="sd"> Args:</span>
+<span class="sd"> coordinates: an array of coordinates (long, lat)</span>
+<span class="sd"> json_projection: a json document indicating the fields that appear in the results</span>
+
+<span class="sd"> Returns:</span>
+<span class="sd"> doc_json: a json document or None</span>
+<span class="sd"> """</span>
+ <span class="n">results</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">near</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">collection_neighbourhoods</span><span class="p">,</span> <span class="n">coordinates</span><span class="p">,</span> <span class="n">json_projection</span><span class="p">,</span> <span class="mi">1</span><span class="p">)</span> <span class="c1"># distance = 1 meter</span>
+ <span class="k">if</span> <span class="nb">len</span><span class="p">(</span><span class="n">results</span><span class="p">)</span> <span class="o">==</span> <span class="mi">0</span><span class="p">:</span>
+ <span class="k">return</span> <span class="kc">None</span>
+ <span class="k">return</span> <span class="n">results</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span>
+</pre></div>
+
+ </details>
+
+ <div class="docstring"><p>Finds the document (neighbourhood) containing the given coordinates. Uses near() since geo_within() requires a
+Polygon.
+Careful: the near() operator may return several neighbourhoods (low probability since distance = 1 meter) and
+only the first one is returned.</p>
+
+<p>Args:
+ coordinates: an array of coordinates (long, lat)
+ json_projection: a json document indicating the fields that appear in the results</p>
+
+<p>Returns:
+ doc_json: a json document or None</p>
+</div>
+
+
+ </div>
+ <div id="Mongiris.near" class="classattr">
+ <div class="attr function"><a class="headerlink" href="#Mongiris.near">#  </a>
+
+
+ <span class="def">def</span>
+ <span class="name">near</span><span class="signature">(
+ self,
+ collection,
+ coordinates,
+ json_projection=None,
+ distance_max=2000
+)</span>:
+ </div>
+
+ <details>
+ <summary>View Source</summary>
+ <div class="codehilite"><pre><span></span> <span class="k">def</span> <span class="nf">near</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">collection</span><span class="p">,</span> <span class="n">coordinates</span><span class="p">,</span> <span class="n">json_projection</span><span class="o">=</span><span class="kc">None</span><span class="p">,</span> <span class="n">distance_max</span><span class="o">=</span><span class="mi">2000</span><span class="p">):</span>
+ <span class="sd">"""</span>
+<span class="sd"> Finds all documents from given collection and which are near the given geometry (according to distance_max).</span>
+
+<span class="sd"> Args:</span>
+<span class="sd"> collection: a string representing the collection name</span>
+<span class="sd"> coordinates: an array of coordinates (long, lat) - near only accepts Point</span>
+<span class="sd"> json_projection: a json document indicating the fields that appear in the results</span>
+<span class="sd"> distance_max: the maximum distance of resulting iris, in meters</span>
+
+<span class="sd"> Returns:</span>
+<span class="sd"> doc_json: a cursor (set of documents)</span>
+<span class="sd"> """</span>
+ <span class="n">geometry</span> <span class="o">=</span> <span class="n">Mongiris</span><span class="o">.</span><span class="n">get_geojson_point</span><span class="p">(</span><span class="n">coordinates</span><span class="p">)</span>
+ <span class="n">cursor</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">find_documents</span><span class="p">(</span><span class="n">collection</span><span class="p">,</span> <span class="p">{</span><span class="s2">"geometry"</span><span class="p">:</span> <span class="p">{</span><span class="s2">"$near"</span><span class="p">:</span> <span class="p">{</span>
+ <span class="s2">"$geometry"</span><span class="p">:</span> <span class="n">geometry</span><span class="p">,</span> <span class="s2">"$maxDistance"</span><span class="p">:</span> <span class="n">distance_max</span><span class="p">}}},</span> <span class="n">json_projection</span><span class="p">)</span>
+ <span class="n">doc_json</span> <span class="o">=</span> <span class="n">Mongiris</span><span class="o">.</span><span class="n">bson_to_json</span><span class="p">(</span><span class="n">cursor</span><span class="p">)</span>
+ <span class="k">return</span> <span class="n">doc_json</span>
+</pre></div>
+
+ </details>
+
+ <div class="docstring"><p>Finds all documents from given collection and which are near the given geometry (according to distance_max).</p>
+
+<p>Args:
+ collection: a string representing the collection name
+ coordinates: an array of coordinates (long, lat) - near only accepts Point
+ json_projection: a json document indicating the fields that appear in the results
+ distance_max: the maximum distance of resulting iris, in meters</p>
+
+<p>Returns:
+ doc_json: a cursor (set of documents)</p>
+</div>
+
+
+ </div>
+ <div id="Mongiris.adjacent" class="classattr">
+ <div class="attr function"><a class="headerlink" href="#Mongiris.adjacent">#  </a>
+
+ <div class="decorator">@staticmethod</div>
+
+ <span class="def">def</span>
+ <span class="name">adjacent</span><span class="signature">(
+ collection,
+ geometry,
+ json_projection=None,
+ distance=20,
+ exclude_geometry=None
+)</span>:
+ </div>
+
+ <details>
+ <summary>View Source</summary>
+ <div class="codehilite"><pre><span></span> <span class="nd">@staticmethod</span>
+ <span class="k">def</span> <span class="nf">adjacent</span><span class="p">(</span><span class="n">collection</span><span class="p">,</span> <span class="n">geometry</span><span class="p">,</span> <span class="n">json_projection</span><span class="o">=</span><span class="kc">None</span><span class="p">,</span> <span class="n">distance</span><span class="o">=</span><span class="mi">20</span><span class="p">,</span> <span class="n">exclude_geometry</span><span class="o">=</span><span class="kc">None</span><span class="p">):</span>
+ <span class="sd">"""</span>
+<span class="sd"> Finds all adjacent neighbors of a neighbourhood represented by geometry.</span>
+<span class="sd"> No adjacent function, so use all coordinates of an iris and find the closest neighbourhood (according to</span>
+<span class="sd"> distance). Could be done directly with near(), but near() is less accurate and thus incomplete.</span>
+
+<span class="sd"> Args:</span>
+<span class="sd"> collection: a string representing the collection name</span>
+<span class="sd"> geometry: a geojson geometry (Point, Polygon, etc.)</span>
+<span class="sd"> json_projection: a json document indicating the fields that appear in the results</span>
+<span class="sd"> distance: the maximum distance for an adjacent neighbour, in meters (10 to 50 meters are fine)</span>
+<span class="sd"> exclude_geometry: the document _id of the neighbourhood represented by geometry, if it needs to be excluded</span>
+
+<span class="sd"> Returns:</span>
+<span class="sd"> doc_json: a cursor (set of documents)</span>
+<span class="sd"> """</span>
+ <span class="n">results</span> <span class="o">=</span> <span class="nb">list</span><span class="p">()</span>
+ <span class="n">results_ids</span> <span class="o">=</span> <span class="nb">list</span><span class="p">()</span>
+ <span class="k">if</span> <span class="n">exclude_geometry</span> <span class="ow">is</span> <span class="ow">not</span> <span class="kc">None</span><span class="p">:</span> <span class="c1"># to exclude the neighbourhood represented by geometry, add it to the results ids</span>
+ <span class="n">results_ids</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="n">exclude_geometry</span><span class="p">)</span>
+ <span class="k">for</span> <span class="n">coords</span> <span class="ow">in</span> <span class="n">geometry</span><span class="p">[</span><span class="s2">"coordinates"</span><span class="p">][</span><span class="mi">0</span><span class="p">]:</span>
+ <span class="n">geometry_coords</span> <span class="o">=</span> <span class="n">Mongiris</span><span class="o">.</span><span class="n">get_geojson_point</span><span class="p">(</span><span class="n">coords</span><span class="p">)</span>
+ <span class="n">cursor</span> <span class="o">=</span> <span class="n">collection</span><span class="o">.</span><span class="n">find</span><span class="p">({</span><span class="s2">"geometry"</span><span class="p">:</span> <span class="p">{</span><span class="s2">"$near"</span><span class="p">:</span> <span class="p">{</span><span class="s2">"$geometry"</span><span class="p">:</span> <span class="n">geometry_coords</span><span class="p">,</span>
+ <span class="s2">"$maxDistance"</span><span class="p">:</span> <span class="n">distance</span><span class="p">}}},</span> <span class="n">json_projection</span><span class="p">)</span>
+ <span class="k">for</span> <span class="n">doc</span> <span class="ow">in</span> <span class="n">cursor</span><span class="p">:</span>
+ <span class="n">doc_id</span> <span class="o">=</span> <span class="n">doc</span><span class="p">[</span><span class="s2">"_id"</span><span class="p">]</span>
+ <span class="k">if</span> <span class="n">doc_id</span> <span class="ow">not</span> <span class="ow">in</span> <span class="n">results_ids</span><span class="p">:</span> <span class="c1"># add the new adjacent iris if not already in the results</span>
+ <span class="n">results</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="n">doc</span><span class="p">)</span>
+ <span class="n">results_ids</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="n">doc_id</span><span class="p">)</span>
+ <span class="n">doc_json</span> <span class="o">=</span> <span class="n">Mongiris</span><span class="o">.</span><span class="n">bson_to_json</span><span class="p">(</span><span class="n">results</span><span class="p">)</span>
+ <span class="k">return</span> <span class="n">doc_json</span>
+</pre></div>
+
+ </details>
+
+ <div class="docstring"><p>Finds all adjacent neighbors of a neighbourhood represented by geometry.
+No adjacent function, so use all coordinates of an iris and find the closest neighbourhood (according to
+distance). Could be done directly with near(), but near() is less accurate and thus incomplete.</p>
+
+<p>Args:
+ collection: a string representing the collection name
+ geometry: a geojson geometry (Point, Polygon, etc.)
+ json_projection: a json document indicating the fields that appear in the results
+ distance: the maximum distance for an adjacent neighbour, in meters (10 to 50 meters are fine)
+ exclude_geometry: the document _id of the neighbourhood represented by geometry, if it needs to be excluded</p>
+
+<p>Returns:
+ doc_json: a cursor (set of documents)</p>
+</div>
+
+
+ </div>
+ </section>
+ </main>
</body>
</html>
\ No newline at end of file
diff --git a/doc/index.html b/doc/index.html
deleted file mode 100644
index 4e487a3..0000000
--- a/doc/index.html
+++ /dev/null
@@ -1,56 +0,0 @@
-<!doctype html>
-<html lang="en">
-<head>
-<meta charset="utf-8">
-<meta name="viewport" content="width=device-width, initial-scale=1, minimum-scale=1" />
-<meta name="generator" content="pdoc 0.6.3" />
-<title>Package mongiris documentation</title>
-<meta name="description" content="" />
-<link href='https://cdnjs.cloudflare.com/ajax/libs/normalize/8.0.0/normalize.min.css' rel='stylesheet'>
-<link href='https://cdnjs.cloudflare.com/ajax/libs/10up-sanitize.css/8.0.0/sanitize.min.css' rel='stylesheet'>
-<link href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/9.12.0/styles/github.min.css" rel="stylesheet">
-<style>.flex{display:flex !important}body{line-height:1.5em}#content{padding:20px}#sidebar{padding:30px;overflow:hidden}.http-server-breadcrumbs{font-size:130%;margin:0 0 15px 0}#footer{font-size:.75em;padding:5px 30px;border-top:1px solid #ddd;text-align:right}#footer p{margin:0 0 0 1em;display:inline-block}#footer p:last-child{margin-right:30px}h1,h2,h3,h4,h5{font-weight:300}h1{font-size:2.5em;line-height:1.1em}h2{font-size:1.75em;margin:1em 0 .50em 0}h3{font-size:1.4em;margin:25px 0 10px 0}h4{margin:0;font-size:105%}a{color:#058;text-decoration:none;transition:color .3s ease-in-out}a:hover{color:#e82}.title code{font-weight:bold}h2[id^="header-"]{margin-top:2em}.ident{color:#900}pre code{background:#f8f8f8;font-size:.8em;line-height:1.4em}code{background:#f2f2f1;padding:1px 4px;overflow-wrap:break-word}h1 code{background:transparent}pre{background:#f8f8f8;border:0;border-top:1px solid #ccc;border-bottom:1px solid #ccc;margin:1em 0;padding:1ex}#http-server-module-list{display:flex;flex-flow:column}#http-server-module-list div{display:flex}#http-server-module-list dt{min-width:10%}#http-server-module-list p{margin-top:0}.toc ul,#index{list-style-type:none;margin:0;padding:0}#index code{background:transparent}#index h3{border-bottom:1px solid #ddd}#index ul{padding:0}#index h4{font-weight:bold}#index h4 + ul{margin-bottom:.6em}@media (min-width:200ex){#index .two-column{column-count:2}}@media (min-width:300ex){#index .two-column{column-count:3}}dl{margin-bottom:2em}dl dl:last-child{margin-bottom:4em}dd{margin:0 0 1em 3em}#header-classes + dl > dd{margin-bottom:3em}dd dd{margin-left:2em}dd p{margin:10px 0}.name{background:#eee;font-weight:bold;font-size:.85em;padding:5px 10px;display:inline-block;min-width:40%}.name:hover{background:#e0e0e0}.name > span:first-child{white-space:nowrap}.name.class > span:nth-child(2){margin-left:.4em}.inherited{color:#999;border-left:5px solid #eee;padding-left:1em}.inheritance em{font-style:normal;font-weight:bold}.desc h2{font-weight:400;font-size:1.25em}.desc h3{font-size:1em}.desc dt code{background:inherit}.source summary{color:#666;text-align:right;font-weight:400;font-size:.8em;text-transform:uppercase;cursor:pointer}.source pre{max-height:500px;overflow:auto;margin:0}.source pre code{font-size:12px;overflow:visible}.hlist{list-style:none}.hlist li{display:inline}.hlist li:after{content:',\2002'}.hlist li:last-child:after{content:none}.hlist .hlist{display:inline;padding-left:1em}img{max-width:100%}.admonition{padding:.1em .5em;margin-bottom:1em}.admonition-title{font-weight:bold}.admonition.note,.admonition.info,.admonition.important{background:#aef}.admonition.todo,.admonition.versionadded,.admonition.tip,.admonition.hint{background:#dfd}.admonition.warning,.admonition.versionchanged,.admonition.deprecated{background:#fd4}.admonition.error,.admonition.danger,.admonition.caution{background:lightpink}</style>
-<style media="screen and (min-width: 700px)">@media screen and (min-width:700px){#sidebar{width:30%}#content{width:70%;max-width:100ch;padding:3em 4em;border-left:1px solid #ddd}pre code{font-size:1em}.item .name{font-size:1em}main{display:flex;flex-direction:row-reverse;justify-content:flex-end}.toc ul ul,#index ul{padding-left:1.5em}.toc > ul > li{margin-top:.5em}}</style>
-<style media="print">@media print{#sidebar h1{page-break-before:always}.source{display:none}}@media print{*{background:transparent !important;color:#000 !important;box-shadow:none !important;text-shadow:none !important}a[href]:after{content:" (" attr(href) ")";font-size:90%}a[href][title]:after{content:none}abbr[title]:after{content:" (" attr(title) ")"}.ir a:after,a[href^="javascript:"]:after,a[href^="#"]:after{content:""}pre,blockquote{border:1px solid #999;page-break-inside:avoid}thead{display:table-header-group}tr,img{page-break-inside:avoid}img{max-width:100% !important}@page{margin:0.5cm}p,h2,h3{orphans:3;widows:3}h1,h2,h3,h4,h5,h6{page-break-after:avoid}}</style>
-</head>
-<body>
-<main>
-<article id="content">
-<header>
-<h1 class="title">Package <code>mongiris</code></h1>
-</header>
-<section id="section-intro">
-The package <code>mongiris</code> consists of two modules:
-<ul>
- <li><a href="api.html">api</a>, for manipulating IRIS data.</li>
- <li><a href="integrator.html">integrator</a>, for integrating data sources. There should be no need to run this module since the MongoDB dumps are provided.</li>
-</ul>
-
-</section>
-</article>
- <nav id="sidebar">
-<h1>Index</h1>
-<div class="toc">
-<ul></ul>
-</div>
-<ul id="index">
-<li><h3><a href="#header-modules">Modules</a></h3>
-<ul>
-<li>
-<h4><code><a title="api" href="api.html">api</a></code></h4>
-</li>
-<li><h4><code><a title="integrator" href="integrator.html">integrator</a></code></h4>
-</li>
-</ul>
-</li>
-</ul>
-</nav>
-</main>
-<footer id="footer">
-<p>Generated by <a href="https://pdoc3.github.io/pdoc"><cite>pdoc</cite> 0.6.3</a>.</p>
-</footer>
-<script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/9.12.0/highlight.min.js"></script>
-<script>hljs.initHighlightingOnLoad()</script>
-</main>
-</body>
-</html>
\ No newline at end of file
diff --git a/doc/integrator.html b/doc/integrator.html
deleted file mode 100644
index 84b0555..0000000
--- a/doc/integrator.html
+++ /dev/null
@@ -1,390 +0,0 @@
-<!doctype html>
-<html lang="en">
-<head>
-<meta charset="utf-8">
-<meta name="viewport" content="width=device-width, initial-scale=1, minimum-scale=1" />
-<meta name="generator" content="pdoc 0.6.3" />
-<title>integrator API documentation</title>
-<meta name="description" content="" />
-<link href='https://cdnjs.cloudflare.com/ajax/libs/normalize/8.0.0/normalize.min.css' rel='stylesheet'>
-<link href='https://cdnjs.cloudflare.com/ajax/libs/10up-sanitize.css/8.0.0/sanitize.min.css' rel='stylesheet'>
-<link href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/9.12.0/styles/github.min.css" rel="stylesheet">
-<style>.flex{display:flex !important}body{line-height:1.5em}#content{padding:20px}#sidebar{padding:30px;overflow:hidden}.http-server-breadcrumbs{font-size:130%;margin:0 0 15px 0}#footer{font-size:.75em;padding:5px 30px;border-top:1px solid #ddd;text-align:right}#footer p{margin:0 0 0 1em;display:inline-block}#footer p:last-child{margin-right:30px}h1,h2,h3,h4,h5{font-weight:300}h1{font-size:2.5em;line-height:1.1em}h2{font-size:1.75em;margin:1em 0 .50em 0}h3{font-size:1.4em;margin:25px 0 10px 0}h4{margin:0;font-size:105%}a{color:#058;text-decoration:none;transition:color .3s ease-in-out}a:hover{color:#e82}.title code{font-weight:bold}h2[id^="header-"]{margin-top:2em}.ident{color:#900}pre code{background:#f8f8f8;font-size:.8em;line-height:1.4em}code{background:#f2f2f1;padding:1px 4px;overflow-wrap:break-word}h1 code{background:transparent}pre{background:#f8f8f8;border:0;border-top:1px solid #ccc;border-bottom:1px solid #ccc;margin:1em 0;padding:1ex}#http-server-module-list{display:flex;flex-flow:column}#http-server-module-list div{display:flex}#http-server-module-list dt{min-width:10%}#http-server-module-list p{margin-top:0}.toc ul,#index{list-style-type:none;margin:0;padding:0}#index code{background:transparent}#index h3{border-bottom:1px solid #ddd}#index ul{padding:0}#index h4{font-weight:bold}#index h4 + ul{margin-bottom:.6em}@media (min-width:200ex){#index .two-column{column-count:2}}@media (min-width:300ex){#index .two-column{column-count:3}}dl{margin-bottom:2em}dl dl:last-child{margin-bottom:4em}dd{margin:0 0 1em 3em}#header-classes + dl > dd{margin-bottom:3em}dd dd{margin-left:2em}dd p{margin:10px 0}.name{background:#eee;font-weight:bold;font-size:.85em;padding:5px 10px;display:inline-block;min-width:40%}.name:hover{background:#e0e0e0}.name > span:first-child{white-space:nowrap}.name.class > span:nth-child(2){margin-left:.4em}.inherited{color:#999;border-left:5px solid #eee;padding-left:1em}.inheritance em{font-style:normal;font-weight:bold}.desc h2{font-weight:400;font-size:1.25em}.desc h3{font-size:1em}.desc dt code{background:inherit}.source summary{color:#666;text-align:right;font-weight:400;font-size:.8em;text-transform:uppercase;cursor:pointer}.source pre{max-height:500px;overflow:auto;margin:0}.source pre code{font-size:12px;overflow:visible}.hlist{list-style:none}.hlist li{display:inline}.hlist li:after{content:',\2002'}.hlist li:last-child:after{content:none}.hlist .hlist{display:inline;padding-left:1em}img{max-width:100%}.admonition{padding:.1em .5em;margin-bottom:1em}.admonition-title{font-weight:bold}.admonition.note,.admonition.info,.admonition.important{background:#aef}.admonition.todo,.admonition.versionadded,.admonition.tip,.admonition.hint{background:#dfd}.admonition.warning,.admonition.versionchanged,.admonition.deprecated{background:#fd4}.admonition.error,.admonition.danger,.admonition.caution{background:lightpink}</style>
-<style media="screen and (min-width: 700px)">@media screen and (min-width:700px){#sidebar{width:30%}#content{width:70%;max-width:100ch;padding:3em 4em;border-left:1px solid #ddd}pre code{font-size:1em}.item .name{font-size:1em}main{display:flex;flex-direction:row-reverse;justify-content:flex-end}.toc ul ul,#index ul{padding-left:1.5em}.toc > ul > li{margin-top:.5em}}</style>
-<style media="print">@media print{#sidebar h1{page-break-before:always}.source{display:none}}@media print{*{background:transparent !important;color:#000 !important;box-shadow:none !important;text-shadow:none !important}a[href]:after{content:" (" attr(href) ")";font-size:90%}a[href][title]:after{content:none}abbr[title]:after{content:" (" attr(title) ")"}.ir a:after,a[href^="javascript:"]:after,a[href^="#"]:after{content:""}pre,blockquote{border:1px solid #999;page-break-inside:avoid}thead{display:table-header-group}tr,img{page-break-inside:avoid}img{max-width:100% !important}@page{margin:0.5cm}p,h2,h3{orphans:3;widows:3}h1,h2,h3,h4,h5,h6{page-break-after:avoid}}</style>
-</head>
-<body>
-<main>
-<article id="content">
-<header>
-<h1 class="title">Module <code>integrator</code></h1>
-</header>
-<section id="section-intro">
-<details class="source">
-<summary>Source code</summary>
-<pre><code class="python">#!/usr/bin/env python
-# encoding: utf-8
-# =============================================================================
-# Integrator: perform the integration of different data sources to produce MongoDB documents (GeoJSON format) containing
-# IRIS information (~640 or ~350 INSEE indicators, depending on the IRIS).
-# This file does not need to be run because the MongoDB dump is provided (unless for integrating new data sources).
-# =============================================================================
-# Path to MongoDB tools (under MacOS): /Applications/MongoDB.app/Contents/Resources/Vendor/mongodb/bin/
-# Export and import a local database (metadata/indexes included, option dryRun for testing, several files):
-# mongodump --db dbinsee --verbose -o dump/
-# mongorestore --db dbinsee --dir dump/dbinsee --verbose --dryRun
-# Export and import a local database (metadata/indexes included, option dryRun for testing, single binary file):
-# mongodump --db dbinsee --verbose --archive=dbinsee.bin
-# mongorestore --archive=dbinsee.bin --verbose
-# Export and import in JSON:
-# ./mongoexport --db dbinsee --out ~/dump-iris.json
-# ./mongoimport --db dbinsee --file ~/dump-iris.json
-# =============================================================================
-
-import os
-import logging
-from mongiris import config
-from mongiris import xls_utils
-from mongiris import api
-
-
-def get_all_xlsx_files(dir_sources):
- """
- Returns a list of spreadsheets files to be integrated.
-
- Args:
- dir_sources: path to a directory containing data sources (spreadsheets from INSEE)
-
- Returns:
- insee_files: a list of filepaths (to xls files)
-
- """
- insee_files = list()
- for file in os.listdir(dir_sources):
- filepath = os.path.join(config.insee_dir, file)
- if os.path.isfile(filepath) and filepath.endswith(".xls"):
- insee_files.append(filepath)
- return insee_files
-
-
-def integrate_xls_file(connection, xls_file):
- """
- Integrates data from an xsl file : the 3 collections may be updated. First, extracts information about the source
- (e.g., title, date) and inserts a document for that source in 'collsources'. Next extracts information about the
- indicators (e.g., short name, long name) and updates/inserts a document in 'collindic'. Finally for each line (IRIS)
- in the spreadsheet, updates corresponding document with new indicators.
-
- Args:
- connection: an object representing the database connection
- xls_file: a csv file path containing INSEE indicators
- """
- indicator_metadata, indicators, source_metadata = xls_utils.parse_xls_to_dict(xls_file)
-
- # add the source metadata into collection_sources
- doc = connection.find_one_document(connection.collection_sources, {"filename": xls_file})
- if doc is None:
- connection.insert_one_document(connection.collection_sources, source_metadata)
-
- # add the indicators information into collection_indic
- for ind in indicator_metadata:
- short_name = ind[config.geojson_shortname_label]
- doc = connection.find_one_document(connection.collection_indic, {config.geojson_shortname_label: short_name})
- if doc is not None: # only update field from_insee_files, $addToSet does not add duplicate values
- connection.update_one_document(connection.collection_indic, {config.geojson_shortname_label: short_name},
- {"$addToSet": {config.geojson_from_files_label: xls_file}})
- else: # add the document
- connection.insert_one_document(connection.collection_indic, ind)
-
- # add the indicators values into collection_iris
- not_found_iris = found_iris = nb_replacements = 0
- for code_iris, indics in indicators.items():
- doc = connection.get_iris_from_code(code_iris)
- if doc is None:
- not_found_iris += 1
- else:
- doc_id = doc['properties']['CODE_IRIS']
- found_iris += 1
- need_replacement = False
- doc_changes = {"$set": dict()} # an update document containing the new fields
- for ind, value in indics.items():
- if ind in config.labels_dictionary_init: # main indicator, do not replace it if already there
- if ind not in doc['properties']: # general information (code iris, city name, etc.)
- doc_changes["$set"]["properties." + ind] = value
- need_replacement = True
- else: # raw indicator
- if ind not in doc['properties'][config.geojson_raw_indicators_label]: # add this value
- doc_changes["$set"]["properties." + config.geojson_raw_indicators_label + "." + ind] = value
- need_replacement = True
-
- if need_replacement: # replace the old doc by new doc
- res = connection.update_one_document(connection.collection_iris, {'properties.CODE_IRIS': doc_id}, doc_changes)
- nb_replacements += res.modified_count
-
- logger.info(f"\t\t{xls_file}: {found_iris} found iris, {not_found_iris} not found iris, {nb_replacements} updates")
- return True
-
-
-def integrate(connection, dir_sources):
- """
- Main integration method: parses a directory of data sources, and call the `integrate_xls_file` function for each
- data source.
-
- Args:
- connection: an object representing the database connection
- dir_sources: path to a directory containing data sources (spreadsheets from INSEE)
- """
- logger.info("Searching xlsx files...")
- insee_files = get_all_xlsx_files(dir_sources) # get the list of all xlsx files to be integrated
- logger.info(f"Found a total of {len(insee_files)} xlsx files to be integrated.")
- # insee_files = [] # roughly 10-20 mins execution time for one data source
- logger.info(f'Selected {len(insee_files)} xlsx files to be integrated.')
-
- logger.info("Integrating sources files (metadata for source and indicators, data for iris)")
- for file in insee_files: # integrate each xlsx INSEE file (both indicators in IRIS and indicators dict)
- logger.info(f"\t- INSEE xlsx file: {file}")
- integrate_xls_file(connection, file)
- logger.info("Done !")
-
-
-def check_properties(connection):
- """
- Computes and prints statistics on the IRIS collection, mainly the number of indicators per document.
- Args:
- connection: an object representing the database connection
- """
- docs = connection.find_documents(connection.collection_iris, {}, )
- counts = dict()
- for doc in docs:
- nb = len(doc['properties'][config.geojson_raw_indicators_label])
- if nb not in counts:
- counts[nb] = 0
- counts[nb] += 1
- print(counts)
-
-
-#########################
-# main integration script
-#########################
-
-if __name__ == '__main__':
-
- logging.basicConfig(format='[%(levelname)s] - %(name)s - %(asctime)s : %(message)s')
- logger = logging.getLogger()
- logger.setLevel(logging.INFO)
-
- connection = api.Mongiris() # database connection
- integrate(connection, config.insee_dir) # integrating data sources
- check_properties(connection) # stats about properties 5min execution {350: 36530, 638: 11738, 615: 1057, 373: 79}</code></pre>
-</details>
-</section>
-<section>
-</section>
-<section>
-</section>
-<section>
-<h2 class="section-title" id="header-functions">Functions</h2>
-<dl>
-<dt id="integrator.check_properties"><code class="name flex">
-<span>def <span class="ident">check_properties</span></span>(<span>connection)</span>
-</code></dt>
-<dd>
-<section class="desc"><p>Computes and prints statistics on the IRIS collection, mainly the number of indicators per document.</p>
-<h2 id="args">Args</h2>
-<dl>
-<dt><strong><code>connection</code></strong></dt>
-<dd>an object representing the database connection</dd>
-</dl></section>
-<details class="source">
-<summary>Source code</summary>
-<pre><code class="python">def check_properties(connection):
- """
- Computes and prints statistics on the IRIS collection, mainly the number of indicators per document.
- Args:
- connection: an object representing the database connection
- """
- docs = connection.find_documents(connection.collection_iris, {}, )
- counts = dict()
- for doc in docs:
- nb = len(doc['properties'][config.geojson_raw_indicators_label])
- if nb not in counts:
- counts[nb] = 0
- counts[nb] += 1
- print(counts)</code></pre>
-</details>
-</dd>
-<dt id="integrator.get_all_xlsx_files"><code class="name flex">
-<span>def <span class="ident">get_all_xlsx_files</span></span>(<span>dir_sources)</span>
-</code></dt>
-<dd>
-<section class="desc"><p>Returns a list of spreadsheets files to be integrated.</p>
-<h2 id="args">Args</h2>
-<dl>
-<dt><strong><code>dir_sources</code></strong></dt>
-<dd>path to a directory containing data sources (spreadsheets from INSEE)</dd>
-</dl>
-<h2 id="returns">Returns</h2>
-<dl>
-<dt><strong><code>insee_files</code></strong></dt>
-<dd>a list of filepaths (to xls files)</dd>
-</dl></section>
-<details class="source">
-<summary>Source code</summary>
-<pre><code class="python">def get_all_xlsx_files(dir_sources):
- """
- Returns a list of spreadsheets files to be integrated.
-
- Args:
- dir_sources: path to a directory containing data sources (spreadsheets from INSEE)
-
- Returns:
- insee_files: a list of filepaths (to xls files)
-
- """
- insee_files = list()
- for file in os.listdir(dir_sources):
- filepath = os.path.join(config.insee_dir, file)
- if os.path.isfile(filepath) and filepath.endswith(".xls"):
- insee_files.append(filepath)
- return insee_files</code></pre>
-</details>
-</dd>
-<dt id="integrator.integrate"><code class="name flex">
-<span>def <span class="ident">integrate</span></span>(<span>connection, dir_sources)</span>
-</code></dt>
-<dd>
-<section class="desc"><p>Main integration method: parses a directory of data sources, and call the <a title="integrator.integrate_xls_file" href="#integrator.integrate_xls_file"><code>integrate_xls_file()</code></a> function for each
-data source.</p>
-<h2 id="args">Args</h2>
-<dl>
-<dt><strong><code>connection</code></strong></dt>
-<dd>an object representing the database connection</dd>
-<dt><strong><code>dir_sources</code></strong></dt>
-<dd>path to a directory containing data sources (spreadsheets from INSEE)</dd>
-</dl></section>
-<details class="source">
-<summary>Source code</summary>
-<pre><code class="python">def integrate(connection, dir_sources):
- """
- Main integration method: parses a directory of data sources, and call the `integrate_xls_file` function for each
- data source.
-
- Args:
- connection: an object representing the database connection
- dir_sources: path to a directory containing data sources (spreadsheets from INSEE)
- """
- logger.info("Searching xlsx files...")
- insee_files = get_all_xlsx_files(dir_sources) # get the list of all xlsx files to be integrated
- logger.info(f"Found a total of {len(insee_files)} xlsx files to be integrated.")
- # insee_files = [] # roughly 10-20 mins execution time for one data source
- logger.info(f'Selected {len(insee_files)} xlsx files to be integrated.')
-
- logger.info("Integrating sources files (metadata for source and indicators, data for iris)")
- for file in insee_files: # integrate each xlsx INSEE file (both indicators in IRIS and indicators dict)
- logger.info(f"\t- INSEE xlsx file: {file}")
- integrate_xls_file(connection, file)
- logger.info("Done !")</code></pre>
-</details>
-</dd>
-<dt id="integrator.integrate_xls_file"><code class="name flex">
-<span>def <span class="ident">integrate_xls_file</span></span>(<span>connection, xls_file)</span>
-</code></dt>
-<dd>
-<section class="desc"><p>Integrates data from an xsl file : the 3 collections may be updated. First, extracts information about the source
-(e.g., title, date) and inserts a document for that source in 'collsources'. Next extracts information about the
-indicators (e.g., short name, long name) and updates/inserts a document in 'collindic'. Finally for each line (IRIS)
-in the spreadsheet, updates corresponding document with new indicators.</p>
-<h2 id="args">Args</h2>
-<dl>
-<dt><strong><code>connection</code></strong></dt>
-<dd>an object representing the database connection</dd>
-<dt><strong><code>xls_file</code></strong></dt>
-<dd>a csv file path containing INSEE indicators</dd>
-</dl></section>
-<details class="source">
-<summary>Source code</summary>
-<pre><code class="python">def integrate_xls_file(connection, xls_file):
- """
- Integrates data from an xsl file : the 3 collections may be updated. First, extracts information about the source
- (e.g., title, date) and inserts a document for that source in 'collsources'. Next extracts information about the
- indicators (e.g., short name, long name) and updates/inserts a document in 'collindic'. Finally for each line (IRIS)
- in the spreadsheet, updates corresponding document with new indicators.
-
- Args:
- connection: an object representing the database connection
- xls_file: a csv file path containing INSEE indicators
- """
- indicator_metadata, indicators, source_metadata = xls_utils.parse_xls_to_dict(xls_file)
-
- # add the source metadata into collection_sources
- doc = connection.find_one_document(connection.collection_sources, {"filename": xls_file})
- if doc is None:
- connection.insert_one_document(connection.collection_sources, source_metadata)
-
- # add the indicators information into collection_indic
- for ind in indicator_metadata:
- short_name = ind[config.geojson_shortname_label]
- doc = connection.find_one_document(connection.collection_indic, {config.geojson_shortname_label: short_name})
- if doc is not None: # only update field from_insee_files, $addToSet does not add duplicate values
- connection.update_one_document(connection.collection_indic, {config.geojson_shortname_label: short_name},
- {"$addToSet": {config.geojson_from_files_label: xls_file}})
- else: # add the document
- connection.insert_one_document(connection.collection_indic, ind)
-
- # add the indicators values into collection_iris
- not_found_iris = found_iris = nb_replacements = 0
- for code_iris, indics in indicators.items():
- doc = connection.get_iris_from_code(code_iris)
- if doc is None:
- not_found_iris += 1
- else:
- doc_id = doc['properties']['CODE_IRIS']
- found_iris += 1
- need_replacement = False
- doc_changes = {"$set": dict()} # an update document containing the new fields
- for ind, value in indics.items():
- if ind in config.labels_dictionary_init: # main indicator, do not replace it if already there
- if ind not in doc['properties']: # general information (code iris, city name, etc.)
- doc_changes["$set"]["properties." + ind] = value
- need_replacement = True
- else: # raw indicator
- if ind not in doc['properties'][config.geojson_raw_indicators_label]: # add this value
- doc_changes["$set"]["properties." + config.geojson_raw_indicators_label + "." + ind] = value
- need_replacement = True
-
- if need_replacement: # replace the old doc by new doc
- res = connection.update_one_document(connection.collection_iris, {'properties.CODE_IRIS': doc_id}, doc_changes)
- nb_replacements += res.modified_count
-
- logger.info(f"\t\t{xls_file}: {found_iris} found iris, {not_found_iris} not found iris, {nb_replacements} updates")
- return True</code></pre>
-</details>
-</dd>
-</dl>
-</section>
-<section>
-</section>
-</article>
-<nav id="sidebar">
-<h1>Index</h1>
-<div class="toc">
-<ul></ul>
-</div>
-<ul id="index">
-<li><h3><a href="#header-functions">Functions</a></h3>
-<ul class="">
-<li><code><a title="integrator.check_properties" href="#integrator.check_properties">check_properties</a></code></li>
-<li><code><a title="integrator.get_all_xlsx_files" href="#integrator.get_all_xlsx_files">get_all_xlsx_files</a></code></li>
-<li><code><a title="integrator.integrate" href="#integrator.integrate">integrate</a></code></li>
-<li><code><a title="integrator.integrate_xls_file" href="#integrator.integrate_xls_file">integrate_xls_file</a></code></li>
-</ul>
-</li>
-</ul>
-</nav>
-</main>
-<footer id="footer">
-<p>Generated by <a href="https://pdoc3.github.io/pdoc"><cite>pdoc</cite> 0.6.3</a>.</p>
-</footer>
-<script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/9.12.0/highlight.min.js"></script>
-<script>hljs.initHighlightingOnLoad()</script>
-</body>
-</html>
\ No newline at end of file
diff --git a/setup.py b/setup.py
index 514d030..c60dcd7 100755
--- a/setup.py
+++ b/setup.py
@@ -1,7 +1,7 @@
#!/usr/bin/env python
# mongiris setup.py (uses setup.cfg)
-# pdoc --force --html mongiris/main.py mongiris/integrator.py
+# pdoc mongiris/api.py -o doc
# pandoc paper.md --filter pandoc-citeproc -o paper.pdf
# python3 -m setup bdist_wheel sdist
# python3 -m pip install -e mongiris/
--
GitLab